JBossWS 2.0.GA - JAX-WS User Guide

Bare is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable.

A bare endpoint or client uses a Java bean that represents the entire document payload.

@WebService
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class DocBareServiceImpl
{
 @WebMethod
 public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
 {
 ...
 }
}

The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "SubmitBareRequest", namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", propOrder = { "product" })
@XmlRootElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", name = "SubmitPO")
public class SubmitBareRequest
{
 @XmlElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", required = true)
 private String product;
 
 ...
}

Wrapped is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint recognizable.

A wrapped endpoint or client uses the individual document payload properties. Wrapped is the default and does not have to be declared explicitly.

@WebService
public class DocWrappedServiceImpl
{
 @WebMethod
 @RequestWrapper (className="org.somepackage.SubmitPO")
 @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
 public String submitPO(String product, int quantity)
 {
 ...
 }
}

Note, that with JBossWS the request/response wrapper annotations are not required, they will be generated on demand using sensible defaults.

Dynamic case

In the dynamic case, when nothing is generated, a web service client uses Service.create to createService instances, the following code illustrates this process.

 URL wsdlLocation = new URL("http://example.org/my.wsdl");
 QName serviceName = new QName("http://example.org/sample", "MyService");
 Service service = Service.create(wsdlLocation, serviceName);

Static case

When starting from a WSDL document, a concrete service implementation class MUST be generated by jbossws tools. The generated implementation class will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL) and the servicename (a javax.xml.namespace.QName) respectively.

When using the no-argument constructor, the WSDL location and service name are implicitly taken from the WebServiceClient annotation that decorates the generated class.

The following code snippet shows the generated constructors:

 // Generated Service Class

 @WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl")
 public class StockQuoteService extends javax.xml.ws.Service 
 {
 public StockQuoteService() 
 {
 super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService"));
 }

 public StockQuoteService(String wsdlLocation, QName serviceName) 
 {
 super(wsdlLocation, serviceName);
 }

 ...
}

Section #Dynamic Proxy explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at #Dispatch.

JAX-WS provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a JAX-WS runtime system. #Handler Framework describes the handler framework in detail. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver methods that may be used to configure a set of handlers on a per-service, per-port or per-protocol binding basis.

When a Service instance is used to create a proxy or a Dispatch instance then the handler resolver currently registered with the service is used to create the required handler chain. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies, or Dispatch instances.

[TODO] (JBWS-1512) Provide a sample for Service HandlerResolver

Service instances can be configured with a java.util.concurrent.Executor. The executor willthen be used to invoke any asynchronous callbacks requested by the application. The setExecutor andgetExecutor methods of Service can be used to modify and retrieve the executor configured for aservice.

[TODO] (JBWS-1513) Provide a sample for Service Executor

Handlers that only operate on message context properties and message payloads. Logical handlersare protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlersare handlers that implement javax.xml.ws.handler.LogicalHandler.

Handlers that operate on message context properties and protocol specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a message. Protocol handlers are handlers that implement any interface derived from javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler.

On the service endpoint, handlers are defined using the @HandlerChain annotation.

@WebService
@HandlerChain(file = "jaxws-server-source-handlers.xml")
public class SOAPEndpointSourceImpl
{
 ...
}

The location of the handler chain file supports 2 formats

1. An absolute java.net.URL in externalForm.(ex: http://myhandlers.foo.com/handlerfile1.xml)

2. A relative path from the source file or class file.(ex: bar/handlerfile1.xml)

On the client side, handler can be configured using the @HandlerChain annotation on the SEI or dynamically using the API.

 Service service = Service.create(wsdlURL, serviceName);
 Endpoint port = (Endpoint)service.getPort(Endpoint.class);
 
 BindingProvider bindingProvider = (BindingProvider)port;
 List<Handler> handlerChain = new ArrayList<Handler>();
 handlerChain.add(new LogHandler());
 handlerChain.add(new AuthorizationHandler());
 handlerChain.add(new RoutingHandler());
 bindingProvider.getBinding().setHandlerChain(handlerChain); // important!

There is currently no portable way of doing this in 4.0.5. @WebServiceContext injection will be available with 4.2. In the meantime you can access the message context like this:

CommonMessageContext msgContext = MessageContextAssociation.peekMessageContext(); 
msgContext.setProperty(<Name>, <Value>);

#Logical Handlers are passed a message context of type LogicalMessageContext when invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of amessage. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.

SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.

WS-Addressing is defined by a combination of the following specifications from the W3C Candidate Recommendation 17 August 2005. The WS-Addressing API is standardized by JSR-261 - Java API for XML Web Services Addressing

The following endpoint implementation has a set of operation for a typical stateful shopping chart application.

 @WebService(name = "StatefulEndpoint", targetNamespace = "http://org.jboss.ws/samples/wsaddressing", serviceName = "TestService")
 @EndpointConfig(configName = "Standard WSAddressing Endpoint")
 @HandlerChain(file = "WEB-INF/jaxws-handlers.xml")
 @SOAPBinding(style = SOAPBinding.Style.RPC)
 public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle
 {
 @WebMethod
 public void addItem(String item)
 { ... }
 
 @WebMethod
 public void checkout()
 { ... }
 
 @WebMethod
 public String getItems()
 { ... }
 }

It uses the JAX-WS Endpoint Configuration# Standard WSAddressing Endpoint to enable the server side addressing handler. It processes the incomming WS-Addressing header elements and provides access to them through the JSR-261 API.

The endpoint handler chain

<handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee javaee_web_services_1_2.xsd"><handler-chain><protocol-bindings>##SOAP11_HTTP</protocol-bindings><handler><handler-name>Application Server Handler</handler-name><handler-class>org.jboss.test.ws.jaxws.samples.wsaddressing.ServerHandler</handler-class></handler></handler-chain></handler-chains>

defines an application specific hander that assignes/processes stateful client ids.

On the client side there are simmilar handlers that does the reverse. It uses the JSR-261 API to add WS-Addressing header elements including the clientid association.

The client sets a custom handler chain in the binding

 Service service = Service.create(wsdlURL, serviceName);
 port1 = (StatefulEndpoint)service.getPort(StatefulEndpoint.class);
 BindingProvider bindingProvider = (BindingProvider)port1;

 List<Handler> customHandlerChain = new ArrayList<Handler>();
 customHandlerChain.add(new ClientHandler());
 customHandlerChain.add(new WSAddressingClientHandler());
 bindingProvider.getBinding().setHandlerChain(customHandlerChain);

The WSAddressingClientHandler is provided by JBossWS and reads/writes the addressing properties and puts then into the message context.

A client connecting to the stateful endpoint

 public class AddressingStatefulTestCase extends JBossWSTest
 {
 public void testAddItem() throws Exception
 {
 port1.addItem("Ice Cream");
 port1.addItem("Ferrari");
 
 port2.addItem("Mars Bar");
 port2.addItem("Porsche");
 }
 
 public void testGetItems() throws Exception
 {
 String items1 = port1.getItems();
 assertEquals("[Ice Cream, Ferrari]", items1);
 
 String items2 = port2.getItems();
 assertEquals("[Mars Bar, Porsche]", items2);
 }
 }

SOAP message exchange

Below you see the SOAP messages that are beeing exchanged.

<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'><wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To><wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action><wsa:ReferenceParameters><ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid></wsa:ReferenceParameters></env:Header><env:Body><ns1:addItem xmlns:ns1='http://org.jboss.ws/samples/wsaddr'><String_1>Ice Cream</String_1></ns1:addItem></env:Body></env:Envelope><env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'><wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To><wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action><ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid></env:Header><env:Body><ns1:addItemResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/></env:Body></env:Envelope>
 
 ...
 
<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'><wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To><wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action><wsa:ReferenceParameters><ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid></wsa:ReferenceParameters></env:Header><env:Body><ns1:getItems xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/></env:Body></env:Envelope><env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'><wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To><wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action><ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid></env:Header><env:Body><ns1:getItemsResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'><result>[Ice Cream, Ferrari]</result></ns1:getItemsResponse></env:Body></env:Envelope>

WS-Eventing is defined by the combination of the following specifications:

The following section will introduce the main eventing actors and their responsiblities.

Note

The original eventing specification builds upon WS-Addressing 2004/08. JBossWS however decided to stick to the latest version, which is the W3C candidate release.

It is the users responsibilty to supply the web service endpoints (EventSourceEndpoint, SubscriptionManagerEndpoint) that are required for a complete event source deployment. Fortunatly JBossWS-Eventing already ships with a implementation that can be used right away. All that's left todo is packaging of standard JSR-109 deployment archive that includes the event source specific WSDL and points to the JBossWS-Eventing endpoint implementations.

The relevant steps are:

With JAX-WS the event source setup has actually become quiet easy. All you need to do is to subclass your endpoint implementation from AbstractEventSourceEndpoint and a subscription manager from AbstractSubscriptionManagerEndpoint and finally point that implementation to a event source specific WSDL.

package org.jboss.test.ws.jaxws.samples.wseventing;

import javax.jws.WebService;

import org.jboss.logging.Logger;
import org.jboss.ws.annotation.EndpointConfig;
import org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint;

/**
 * @author Heiko.Braun@jboss.org
 * @version $Id: jaxws-userguide.xml 3847 2007-07-11 11:58:28Z heiko.braun@jboss.com $
 * @since 18.01.2007
 */
@WebService( (1)
 name = "EventSource",
 portName = "EventSourcePort",
 targetNamespace = "http://schemas.xmlsoap.org/ws/2004/08/eventing",
 wsdlLocation = "/WEB-INF/wsdl/sysmon.wsdl", (2)
 endpointInterface = "org.jboss.ws.extensions.eventing.jaxws.EventSourceEndpoint")
@EndpointConfig(configName = "Standard WSAddressing Endpoint") (3)
public class SysmonRegistrationEndpoint extends AbstractEventSourceEndpoint { (4)

 private static final Logger log = Logger.getLogger(SysmonRegistrationEndpoint.class);

 protected Logger getLogger()
 {
 return log;
 }
}

Even though we are already using the annotation driven approach, JBossWS eventing still requires an event source specific WSDL.

The following excerpt shows the relevant WSDL details that describe an event source.

<?xml version="1.0" encoding="UTF-8"?><wsdl:definitions
 targetNamespace="http://www.jboss.org/sysmon"
 xmlns:tns="http://www.jboss.org/sysmon"
 xmlns:wse='http://schemas.xmlsoap.org/ws/2004/08/eventing'
 xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
 xmlns:wsa10='http://www.w3.org/2005/08/addressing'
 xmlns:xs='http://www.w3.org/2001/XMLSchema'
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"><wsdl:import
(1) namespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'
 location='jbwse.wsdl' /><wsdl:types><xs:schema targetNamespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'>
(2) <xs:include schemaLocation='jbwse.xsd'/></xs:schema>

(3) <xs:schema
 targetNamespace="http://www.jboss.org/sysmon"
 elementFormDefault="qualified"
 blockDefault="#all"><xs:element name="SystemStatus"><xs:complexType><xs:sequence><xs:element name="Time " type="xs:dateTime"/><xs:element name="HostName" type="xs:string"/><xs:element name="HostAddress" type="xs:string"/><xs:element name="ActiveThreadCount" type="xs:int"/><xs:element name="FreeMemory" type="xs:string"/><xs:element name="MaxMemory" type="xs:string"/></xs:sequence></xs:complexType></xs:element></xs:schema></wsdl:types><wsdl:message name='SystemInfoMsg'><wsdl:part name='body' element='tns:SystemStatus'/></wsdl:message>

(4) <wsdl:portType name='SystemInfo' wse:EventSource='true'><wsdl:operation name='SysmonOp'><wsdl:output message='tns:SystemInfoMsg'/></wsdl:operation></wsdl:portType><wsdl:binding name="SystemInfoBinding" type="tns:SystemInfo"><soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/><wsdl:operation name="SysmonOp"><soap:operation soapAction=""/><wsdl:output><soap:body use="literal"/></wsdl:output></wsdl:operation></wsdl:binding></wsdl:definitions>

JBossWS-Eventing registeres a event dispatcher within local JNDI tree that can be used to emit notifications from applications.

 java:/EventDispatcher

The event dispatcher interface:

 public interface EventDispatcher
 {
 void dispatch(URI eventSourceNS, Element payload);
 }

Example notification

(1) URI eventSourceURI = new URI("http://http://www.jboss.org/sysmon/SystemInfo");
(2) Element payload = DOMUtils.parse("SOME XML STRING");
 try
 {
 InitialContext iniCtx = getInitialContext();
(3) EventDispatcher delegate = (EventDispatcher)
 iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME);
(4) delegate.dispatch(eventSourceURI, payload);
 }
 catch (Exception e)
 {
 //
 }

The SubscriptionManager MBean is the actual core component that drives the JBossWS-Eventing implementation. It can be accessed through the jmx-console.

 jboss.ws.eventing:service=SubscriptionManager

Management operations exist to monitor and maintain active subscritions and deployed event sources. The current implementation is backed by a ThreadPoolExecutor, that asynchronously delivers messages to event sink endpoints. It can be configured through the following attributes:

In this example we configure both the client and the server to sign the message body. Both also require this from each other. So, if you remove either the client or the server security deployment descriptor, you will notice that the other party will throw a fault explaining that the message did not conform to the proper security requirements.

<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.jboss.com/ws-security/config 
 http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
 (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file>
 (2) <key-store-password>jbossws</key-store-password>
 (3) <trust-store-file>WEB-INF/wsse.truststore</trust-store-file>
 (4) <trust-store-password>jbossws</trust-store-password>
 (5) <config>
 (6) <sign type="x509v3" alias="wsse"/>
 (7) <requires>
 (8) <signature/></requires></config></jboss-ws-security>

<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.jboss.com/ws-security/config 
 http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
 (1) <config>
 (2) <sign type="x509v3" alias="wsse"/>
 (3) <requires>
 (4) <signature/></requires></config></jboss-ws-security>

We did not specify a key store or trust store, because client apps instead use the wsse System properties instead. If this was a web or ejb client (meaning a webservice client in a war or ejb jar file), then we would have specified them in the client descriptor.

SOAP message exchange

Below you see the incomming SOAP message with the details of the security headers ommited. The idea is, that the SOAP body is still plain text, but it is signed in the security header and can therefore not manipulated in transit.

Incomming SOAPMessage

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Header><wsse:Security env:mustUnderstand="1" ...><wsu:Timestamp wsu:Id="timestamp">...</wsu:Timestamp><wsse:BinarySecurityToken ...>
 ...
 </wsse:BinarySecurityToken><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
 ...
 </ds:Signature></wsse:Security></env:Header><env:Body wsu:Id="element-1-1140197309843-12388840" ...><ns1:echoUserType xmlns:ns1="http://org.jboss.ws/samples/wssecurity"><UserType_1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><msg>Kermit</msg></UserType_1></ns1:echoUserType></env:Body></env:Envelope>

The information below has originaly been provided by The Legion of the Bouncy Castle.

The provider can be configured as part of your environment via static registration by adding an entry to the java.security properties file (found in $JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location of your JDK/JRE distribution). You'll find detailed instructions in the file but basically it comes down to adding a line:

 security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider

Where <n> is the preference you want the provider at.

Note

Issues may arise if the Sun provided providers are not first.

Where you put the jar is mostly up to you, although with jdk1.4 the best (and in some cases only) place to have it is in $JAVA_HOME/jre/lib/ext. Under Windows there will normally be a JRE and a JDK install of Java if you think you have installed it correctly and it still doesn't work chances are you have added the provider to the installation not being used.

Note

If you having a hard time understanding how the different trust- and keystore configurationsare used for signature and encryption, then read this thread first:http://www.jboss.org/index.html?module

The above table shows a list of supported endpoint parameter types. The recommended approach is to use the javax.activation.DataHandler classes to represent binary data as service endpoint parameters.

Note

Microsoft endpoints tend to send any data as application/octet-stream. The only Java type that can easily cope with this ambiguity is javax.activation.DataHandler

On the server side MTOM processing is enabled through the @BindingType annotation.JBossWS does handle SOAP1.1 and SOAP1.2. Both come with or without MTOM flavours:

MTOM enabled service implementations

package org.jboss.test.ws.jaxws.samples.xop.doclit;

import javax.ejb.Remote;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.ws.BindingType;

@Remote
@WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE)
@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
public interface MTOMEndpoint {

 [...]
}

MTOM enabled clients

Web service clients can use the same approach described above or rely on the Binding API to enable MTOM(Excerpt taken from the org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase):

[...]
Service service = Service.create(wsdlURL, serviceName);
port = service.getPort(MTOMEndpoint.class);

// enable MTOM
binding = (SOAPBinding)((BindingProvider)port).getBinding();
binding.setMTOMEnabled(true);

Note

You might as well use the JBossWS configuration templates to setup deployment defaults.

Configuration of the jUDDI registry happens via an MBean Service that is deployed in the juddi-service.sar archive in the "all" configuration. The configuration of this service can be done in the jboss-service.xml of the META-INF directory in the juddi-service.sar

Let us look at the individual configuration items that can be changed.

DataSources configuration

<attribute name="DataSourceUrl">java:/DefaultDS</attribute>

Database Tables (Should they be created on start, Should they be dropped on stop, Should they be dropped on start etc)

<attribute name="CreateOnStart">false</attribute><attribute name="DropOnStop">true</attribute><attribute name="DropOnStart">false</attribute>

JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)

<attribute name="ShouldBindJaxr">true</attribute><attribute name="BindJaxr">JAXR</attribute>

Other common configuration:

Add authorized users to access the jUDDI registry. (Add a sql insert statement in a single line)

 Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user 'jboss'

 INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,
 EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN) 
 VALUES ('jboss','JBoss User','jboss@xxx','true','true');

In this section, we will discuss the configuration needed to run the JAXR API. The JAXR configuration relies on System properties passed to the JVM. The System properties that are needed are:

 javax.xml.registry.ConnectionFactoryClass=org.apache.ws.scout.registry.ConnectionFactoryImpl 
 jaxr.query.url=http://localhost:8080/juddi/inquiry 
 jaxr.publish.url=http://localhost:8080/juddi/publish
 juddi.proxy.transportClass=org.jboss.jaxr.juddi.transport.SaajTransport

Please remember to change the hostname from "localhost" to the hostname of the UDDI service/JBoss Server.

You can pass the System Properties to the JVM in the following ways:

 System.setProperty(propertyname, propertyvalue);

There are two categories of API: JAXR Publish API and JAXR Inquiry API. The important JAXR interfaces that any JAXR client code will use are the following.

Let us now look at some of the common programming tasks performed while using the JAXR API:

Getting a JAXR Connection to the registry.

 String queryurl = System.getProperty("jaxr.query.url", "http://localhost:8080/juddi/inquiry");
 String puburl = System.getProperty("jaxr.publish.url", "http://localhost:8080/juddi/publish");

 Properties props = new Properties();
 props.setProperty("javax.xml.registry.queryManagerURL", queryurl);
 props.setProperty("javax.xml.registry.lifeCycleManagerURL", puburl);

 String transportClass = System.getProperty("juddi.proxy.transportClass", "org.jboss.jaxr.juddi.transport.SaajTransport");
 System.setProperty("juddi.proxy.transportClass", transportClass);

 // Create the connection, passing it the configuration properties
 factory = ConnectionFactory.newInstance();
 factory.setProperties(props);
 connection = factory.createConnection();

Authentication with the registry.

 /**
 * Does authentication with the uddi registry
 */
 protected void login() throws JAXRException
 {
 PasswordAuthentication passwdAuth = new PasswordAuthentication(userid, passwd.toCharArray());
 Set creds = new HashSet();
 creds.add(passwdAuth);

 connection.setCredentials(creds);
 }

Save a Business

 /**
 * Creates a Jaxr Organization with 1 or more services
 */
 protected Organization createOrganization(String orgname) throws JAXRException
 {
 Organization org = blm.createOrganization(getIString(orgname));
 org.setDescription(getIString("JBoss Inc"));
 Service service = blm.createService(getIString("JBOSS JAXR Service"));
 service.setDescription(getIString("Services of XML Registry"));
 //Create serviceBinding
 ServiceBinding serviceBinding = blm.createServiceBinding();
 serviceBinding.setDescription(blm.createInternationalString("Test Service Binding"));

 //Turn validation of URI off
 serviceBinding.setValidateURI(false);
 serviceBinding.setAccessURI("http://testjboss.org");

 // Add the serviceBinding to the service
 service.addServiceBinding(serviceBinding);

 User user = blm.createUser();
 org.setPrimaryContact(user);
 PersonName personName = blm.createPersonName("Anil S");
 TelephoneNumber telephoneNumber = blm.createTelephoneNumber();
 telephoneNumber.setNumber("111-111-7777");
 telephoneNumber.setType(null);
 PostalAddress address = blm.createPostalAddress("111", "My Drive", "BuckHead", "GA", "USA", "1111-111", "");
 Collection postalAddresses = new ArrayList();
 postalAddresses.add(address);
 Collection emailAddresses = new ArrayList();
 EmailAddress emailAddress = blm.createEmailAddress("anil@apache.org");
 emailAddresses.add(emailAddress);

 Collection numbers = new ArrayList();
 numbers.add(telephoneNumber);
 user.setPersonName(personName);
 user.setPostalAddresses(postalAddresses);
 user.setEmailAddresses(emailAddresses);
 user.setTelephoneNumbers(numbers);

 ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics", "");
 Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2");
 cScheme.setKey(cKey);
 Classification classification = blm.createClassification(cScheme, "Computer Systems Design and Related Services", "5415");
 org.addClassification(classification);
 ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S", "");
 Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423");
 cScheme1.setKey(cKey1);
 ExternalIdentifier ei = blm.createExternalIdentifier(cScheme1, "D-U-N-S number", "08-146-6849");
 org.addExternalIdentifier(ei);
 org.addService(service);
 return org;
 }

Query a Business

 /**
 * Locale aware Search a business in the registry
 */
 public void searchBusiness(String bizname) throws JAXRException
 {
 try
 {
 // Get registry service and business query manager
 this.getJAXREssentials();

 // Define find qualifiers and name patterns
 Collection findQualifiers = new ArrayList();
 findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
 Collection namePatterns = new ArrayList();
 String pattern = "%" + bizname + "%";
 LocalizedString ls = blm.createLocalizedString(Locale.getDefault(), pattern);
 namePatterns.add(ls);

 // Find based upon qualifier type and values
 BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);

 // check how many organisation we have matched
 Collection orgs = response.getCollection();
 if (orgs == null)
 {
 log.debug(" -- Matched 0 orgs");

 }
 else
 {
 log.debug(" -- Matched " + orgs.size() + " organizations -- ");

 // then step through them
 for (Iterator orgIter = orgs.iterator(); orgIter.hasNext();)
 {
 Organization org = (Organization)orgIter.next();
 log.debug("Org name: " + getName(org));
 log.debug("Org description: " + getDescription(org));
 log.debug("Org key id: " + getKey(org));
 checkUser(org);
 checkServices(org);
 }
 }
 }
 finally
 {
 connection.close();
 }
 }

For more examples of code using the JAXR API, please refer to the resources in the Resources Section.

WS-Policy is defined by the combination of the following specifications:

   * WS-Policy specification

   * WS-Policy-Attachment specification

To attach policies in this manner, the only thing you have to do in a webservice class is to provide a custom wsdl. This will cause JBossws to skip wsdl generation at deploy time, since the wsdl file you provided will be published. Please refer to specification (WS-Policy-Attachment) to learn how to modify wsdl to attach a policy.

Here you find an example of a webservice class and provided wsdl with a policy containing a domain assertion for JBoss wssecurity.

@WebService(name = "Hello", 
targetNamespace = "http://org.jboss.ws/samples/wssecuritypolicy",
wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class HelloJavaBean
{
 private Logger log = Logger.getLogger(HelloJavaBean.class);

 @WebMethod
 public UserType echoUserType(@WebParam(name = "user") UserType in0)
 {
 log.info(in0);
 return in0;
 }
}

<?xml version="1.0" encoding="UTF-8"?><definitions name='HelloService' targetNamespace='http://org.jboss.ws/samples/wssecuritypolicy' xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://org.jboss.ws/samples/wssecurity' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://org.jboss.ws/samples/wssecuritypolicy' xmlns:wsp='http://schemas.xmlsoap.org/ws/2004/09/policy' xmlns:xsd='http://www.w3.org/2001/XMLSchema'><types><xs:schema targetNamespace='http://org.jboss.ws/samples/wssecurity' version='1.0' xmlns:xs='http://www.w3.org/2001/XMLSchema'><xs:complexType name='UserType'><xs:sequence><xs:element minOccurs='0' name='msg' type='xs:string'/></xs:sequence></xs:complexType></xs:schema></types><wsp:Policy wsu:Id='X509EndpointPolicy' xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'><wsp:All><sp:jboss-ws-security xmlns:sp='http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd'><sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file><sp:key-store-password>jbossws</sp:key-store-password><sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file><sp:trust-store-password>jbossws</sp:trust-store-password><sp:config><sp:encrypt alias='wsse' type='x509v3'/><sp:requires><sp:encryption/></sp:requires></sp:config></sp:jboss-ws-security></wsp:All></wsp:Policy><message name='Hello_echoUserType'><part name='user' type='ns1:UserType'/></message><message name='Hello_echoUserTypeResponse'><part name='return' type='ns1:UserType'/></message><portType name='Hello'><operation name='echoUserType' parameterOrder='user'><input message='tns:Hello_echoUserType'/><output message='tns:Hello_echoUserTypeResponse'/></operation></portType><binding name='HelloBinding' type='tns:Hello'><wsp:PolicyReference URI='#X509EndpointPolicy'/><soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/><operation name='echoUserType'><soap:operation soapAction=''/><input><soap:body namespace='http://org.jboss.ws/samples/wssecuritypolicy' use='literal'/></input><output><soap:body namespace='http://org.jboss.ws/samples/wssecuritypolicy' use='literal'/></output></operation></binding><service name='HelloService'><port binding='tns:HelloBinding' name='HelloPort'><soap:address location='REPLACE_WITH_ACTUAL_URL'/></port></service></definitions>

Please note in the wsdl file the wsp:Policy element and the wsp:PolicyReference in 'HelloBinding' binding Element.

Using JBoss proprietary annotation you only have to provide the policy xml, leaving wsdl generation to the JBossWS deployer.

There are two annotations to use, the first one (@PolicyAttachment) containing an array of the second one (@Policy): this lets you have many policies attached to a class or method.In future domain policy implementations might ship domain annotations extending the @Policy annotation to provide needed metadata directly as annotation parameters. The current @Policy annotation takes a reference to a xml file containing a generic policy description written respecting ws-policy specification rules.

/**

@Target(ElementType.TYPE) 
@Retention(RetentionPolicy.RUNTIME)
public @interface PolicyAttachment {
 Policy[] value();
}

@Retention(RetentionPolicy.RUNTIME)
public @interface Policy {
 
 public String policyFileLocation();
 
 public PolicyScopeLevel scope();
}

And here you have the previous section example re-implemented using annotations and xml policy file:

@WebService(name = "Hello", targetNamespace = "http://org.jboss.ws/samples/wssecurityAnnotatedpolicy")
@PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope = PolicyScopeLevel.WSDL_PORT ) })
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class HelloJavaBean
{
 private Logger log = Logger.getLogger(HelloJavaBean.class);

 @WebMethod
 public UserType echoUserType(@WebParam(name = "user") UserType in0)
 {
 log.info(in0);
 return in0;
 }
}

<?xml version="1.0" encoding="UTF-8"?><wsp:Policy wsu:Id="X509EndpointPolicy" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" 
	 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsp:ExactlyOne><wsp:All><sp:jboss-ws-security xmlns:sp="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"><sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file><sp:key-store-password>jbossws</sp:key-store-password><sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file><sp:trust-store-password>jbossws</sp:trust-store-password><sp:config><sp:encrypt type="x509v3" alias="wsse"/><sp:requires><sp:encryption/></sp:requires></sp:config></sp:jboss-ws-security></wsp:All></wsp:ExactlyOne></wsp:Policy>

JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple way to enable SwaRef encoding for DataHandler types is to annotate a payload bean with the @XmlAttachmentRef annotation as shown below:

/**
* Payload bean that will use SwaRef encoding
*/
@XmlRootElement
public class DocumentPayload
{
 private DataHandler data;

 public DocumentPayload()
 {
 }

 public DocumentPayload(DataHandler data)
 {
 this.data = data;
 }
 
 @XmlElement
 @XmlAttachmentRef
 public DataHandler getData()
 {
 return data;
 }

 public void setData(DataHandler data)
 {
 this.data = data;
 }
}

With document wrapped endpoints you may even specify the @XmlAttachmentRef annotation on the service endpoint interface:

@WebService
public interface DocWrappedEndpoint
{
 @WebMethod
 DocumentPayload beanAnnotation(DocumentPayload dhw, String test);

 @WebMethod
 @XmlAttachmentRef
 DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);

}

The message would then refer to the attachment part by CID:

<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header/><env:Body><ns2:parameterAnnotation xmlns:ns2='http://swaref.samples.jaxws.ws.test.jboss.org/'><arg0>cid:0-1180017772935-32455963@ws.jboss.org</arg0><arg1>Wrapped test</arg1></ns2:parameterAnnotation></env:Body></env:Envelope>

If you chose the contract first approach then you need to ensure that any element declaration that should use SwaRef encoding simply refers to wsi:swaRef schema type:

<element name="data" type="wsi:swaRef" 
xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"/>

Any wsi:swaRef schema type would then be mapped to DataHandler.

/**
 * Defines an endpoint or client configuration. 
 * This annotation is valid on an endpoint implementaion bean or a SEI.
 * 
 * @author Heiko.Braun@jboss.org
 * @since 16.01.2007
 */
@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = { ElementType.TYPE })
public @interface EndpointConfig {

 /**
 * The optional config-name element gives the configuration name that must be present in
 * the configuration given by element config-file.
 *
 * Server side default: Standard Endpoint
 * Client side default: Standard Client
 */
 String configName() default "";

 /**
 * The optional config-file element is a URL or resource name for the configuration.
 *
 * Server side default: standard-jaxws-endpoint-config.xml
 * Client side default: standard-jaxws-client-config.xml
 */
 String configFile() default "";
}

/**
 * Provides web context specific meta data to EJB based web service endpoints.
 *
 * @author thomas.diesler@jboss.org
 * @since 26-Apr-2005
 */
@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = { ElementType.TYPE })
public @interface WebContext {

 /** 
 * The contextRoot element specifies the context root that the web service endpoint is deployed to.
 * If it is not specified it will be derived from the deployment short name.
 * 
 * Applies to server side port components only. 
 */
 String contextRoot() default "";
 
 /** 
 * The virtual hosts that the web service endpoint is deployed to.
 * 
 * Applies to server side port components only.
 */
 String[] virtualHosts() default {};
 
 /** 
 * Relative path that is appended to the contextRoot to form fully qualified
 * endpoint address for the web service endpoint.
 * 
 * Applies to server side port components only. 
 */
 String urlPattern() default "";

 /**
 * The authMethod is used to configure the authentication mechanism for the web service. 
 * As a prerequisite to gaining access to any web service which are protected by an authorization
 * constraint, a user must have authenticated using the configured mechanism.
 *
 * Legal values for this element are "BASIC", or "CLIENT-CERT".
 */
 String authMethod() default "";

 /**
 * The transportGuarantee specifies that the communication
 * between client and server should be NONE, INTEGRAL, or
 * CONFIDENTIAL. NONE means that the application does not require any
 * transport guarantees. A value of INTEGRAL means that the application
 * requires that the data sent between the client and server be sent in
 * such a way that it can't be changed in transit. CONFIDENTIAL means
 * that the application requires that the data be transmitted in a
 * fashion that prevents other entities from observing the contents of
 * the transmission. In most cases, the presence of the INTEGRAL or
 * CONFIDENTIAL flag will indicate that the use of SSL is required.
 */
 String transportGuarantee() default "";

 /**
 * A secure endpoint does not by default publish it's wsdl on an unsecure transport.
 * You can override this behaviour by explicitly setting the secureWSDLAccess flag to false.
 * 
 * Protect access to WSDL. See http://jira.jboss.org/jira/browse/JBWS-723 
 */
 boolean secureWSDLAccess() default true;
}

/**
 * Annotation for specifying the JBoss security domain for an EJB
 * 
 * @author <a href="mailto:bill@jboss.org">Bill Burke</a>
 **/
@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
public @interface SecurityDomain
{
 /**
 * The required name for the security domain.
 * 
 * Do not use the JNDI name
 * 
 * Good: "MyDomain"
 * Bad: "java:/jaas/MyDomain"
 */
 String value();
 
 /**
 * The name for the unauthenticated pricipal
 */
 String unauthenticatedPrincipal() default "";
}