JBossWS - FAQ

General

Which version of App Server is JBossWS supported for?

Supported Target Containers

 

Why are my forum posts not answered more quickly?

Posts to the user forum will be dealt with at the community's leisure. If your business is such that you need to rely on qualified answers within a known time frame, the forum might not be your preferred support channel.

 

Are there any samples I can look at?

Yes, samples are available from the JBossWS download page.

 

What are the advantages of JAX-WS over JAX-RPC?

JAX-WS_vs_JAX-RPC

 

 

Development

What do I do if I think there is a bug?

  • Check if it works with the latest sources.
  • Checkout the Road Map if you are using the latest release or the Change Log if you are using another one.
  • Finally, if your bug hasn't been reported yet, please create a JBossWS JIRA issue and attach a sample deployment that allows us to reproduce what you are seeing. Idealy, the sample deployment is a webapp packaged as a war that shows the issue when we click on a link. The war should also contain the sources.

 

Where is the JBossWS source repository?

Please refer to Subversion.

How can I build and install the latest?

Please refer to the development guide: Building_From_Source

Server

How does rewriting of the soap address in WSDL work?

Please refer to the advanced user guide section of JBossWS 4.x or later, or to the user guide's Configuration section (previous JBossWS versions)

 

How do I know what endpoint address is being used?

The endpoint context root is computed as follows

1.) Use the explicit context root from the web meta data

Can be set in jboss-web.xml and is only relevant for JSE endpoints.

2.) Use the explicit context root from @WebContext.contextRoot

Can only be set on EJB endpoints.

3.) Use the explicit context root from webservices/context-root

Can be set in jboss.xml and is only relevant for EJB endpoints.

4.) Use the explicit context root from port-component/port-component-uri

For backward compatibility, this uses the first token from port-component-uri in jboss.xml. It is only relevant for legacy EJB endpoints and should not be used.

5.) Use the implicit context root derived from the deployment name

If the context root is not explicitly set we fall back to the simple deployment name for both JSE and EJB endpoints. If the endpoint is deployed as part of an EAR, the context root is prepended by simple EAR name.

 

The URL pattern is computed as follows

1) Use the explicit url-pattern from the servlet mappings

Must be set in web.xml and is only relevant for JSE endpoints.

2) Use the explicit url-pattern from port-component/port-component-uri

Can be set in jboss.xml and is only relevant for EJB endpoints.

3) Use the explicit url-pattern from @WebContext.urlPattern

Can only be set on EJB endpoints.

4) Use the implicit url-pattern from ejb-name

If the url-pattern for an EJB endpoint is not explicitly set, we fall back to the ejb-name.

 

Examples

@Stateless
@WebService
@WebContext( contextRoot = "/webservices" )
@Remote( UserService.class )
public class ExampleServiceBean implements ExampleService {
    ...
}

Will bind to http://localhost:8080/webservices/ExampleServiceBean

@Stateless
@WebService
@WebContext( contextRoot = "/webservices" , urlPattern="/ExampleService" )
@Remote( UserService.class )
public class ExampleServiceBean implements ExampleService {
    ...
}

Will bind to http://localhost:8080/webservices/ExampleService

The default behavior in jboss 4.0.5 was to use the jar file name followed by the ejb name. This can be replicated by using the WebContext annotation e.g.

@WebService
@WebContext( contextRoot = "/jar-file-name" , urlPattern="/ejb-name" )

 

How to use JDK JMX JConsole with JBossWS?

You must use JDK 5 or above on JBoss server side with the following JVM properties set on the commandline:

JAVA_OPTS="$JAVA_OPTS -Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl"
JAVA_OPTS="$JAVA_OPTS -Djboss.platform.mbeanserver"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote"

Running the jconsole against this configuration will bring up a console that incorporates both the JBoss and JVM MBeans.

For further information follow this link: http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMBeansInJConsole

For JMX information in JBoss AS in general follow this link: http://wiki.jboss.org/wiki/Wiki.jsp?page=FAQJBossJMX

 

Since 3.2.0

Finally, please note you can enable the com.sun.managemente.jmxremote property on client side when running the JBossWS testsuite simply providing the -Dmanagement=true parameter on command line.

eg.

mvn -Ptestsuite,jboss510 -Dmanagement=true test

This will cause the maven build to pass the required properties to the maven surefire test executor. This way you can usr JConsole to analize memory usage, threads, etc. when running the testsuite.

 

Why I'm getting "propertyname is not valid property on class mypackage.jaxws.Propertyname"?

If you are getting the following exception:

org.jboss.ws.WSException: propertyname is not a valid property on class mypackage.jaxws.Propertyname
        at com.sun.xml.bind.v2.runtime.JAXBContextImpl.getElementPropertyAccessor(JAXBContextImpl.java)
        at org.jboss.ws.metadata.acessor.JAXBAccessor$1$1.create(JAXBAccessor.java)

then you are facing the JAX-WS defaults problem. JAX-WS specification gives these requirements on Document Wrapped:

From JAX-WS 2.0 19. April 2006:

3.6.2.1 Document Wrapped:

* Conformance (Default wrapper bean names): In the absence of customizations, the wrapper request bean
  class MUST be named the same as the method and the wrapper response bean class MUST be named the
  same as the method with a "Response" suffix. The first letter of each bean name is capitalized to follow
  Java class naming conventions.
* Conformance (Default wrapper bean package): In the absence of customizations,
  the wrapper beans package UST be a generated jaxws subpackage of the SEI package.
* Conformance (Wrapper bean name clash): Generated bean classes must have unique names within a pack-
  age and MUST NOT clash with other classes in that package. Clashes during generation MUST be reported
  as an error and require user intervention via name customization to correct. Note that some platforms  
  do not distiguish filenames based on case so comparisons MUST ignore case.

That means when you are using JBossWS with Document Wrapped you can't have two methods with same name inside the package without specifying customizations. Thus to solve your problem you have to specify  at least:

  @javax.xml.ws.RequestWrapper(className="package.UniqueClassName")
  @javax.xml.ws.ResponseWrapper(className="package.UniqueClassNameResponse") 

method annotations on all overloaded methods (overloaded here means not overloaded in class but overloaded in package).

 

Client

How do I generate the required artifacts?

JBossWS ships with a set of tools to generate the required JAX-WS artefacts to build client implementations. The wsconsume tool is used to consume the abstract contract (WSDL) and produce annotated Java classes (and optionally sources) that define it. You can run wsconsume from the command line and from an Apache Ant target.

To run wsconsume from the command line, use the scripts available in the bin dir of your JBoss AS installation.

Here is an example of how to run wsconsume from the command line, generating source and class files in the org.foo package, in a custom directory.

wsconsume -k -o custom -p org.foo Example.wsdl

For further informations and examples, also check the top-down development strategy in the user guide.

Finally, if you need JAX-RPC artifacts generation, please refer to the legacy JBossWS tools documentation.

 

How can I leverage the client deployment model?

The WS client deployment model has many advantages over DII. Most Java applications (except the most trivial ones) have a need for registry lookup (JNDI) and management (JMX). A very minimal jboss configuration has a tiny footprint and provides just that. Therefore, you might want to consider running your client app on jboss and manage it through jmx-console and have a layer of indirection for resource lookup through JNDI. Additionally, you could then use the WS client programming model and obtain preconfigured WS clients from JNDI.

 

How can I setup my client to use a proxy?

[5.4.10. HTTP(S) Client Invoker - proxy and basic authentication]

 

What client artifacts are thread safe?

JAX-RCP

javax.xml.rpc.ServiceFactory - Just a factory so yes it is thread safe.

javax.xml.rpc.Service - A factory for calls and stubs so it is thread safe.

javax.xml.rpc.Call - Not thread safe, the API allows for multiple method invocations for a single WS call.

javax.xml.rpc.Stub - Contains properties that may be thread specific. Stub is the interface implemented by the dynamic proxy which delegates to an implementation of Call. So, whatever is true for Call also holds for the dynamic proxy implementing Stub.

 

JAX-WS (JBossWS-Native)

javax.xml.ws.Service - Thread safe

The port proxy returned by getPort(..) methods of Service is not thread safe instead.

 

Also check the Apache CXF FAQ for further info when using JBossWS-CXF stack.

 

What client jars do I need?

For JBossWS 3.x or previous versions, please have a look at wsrunclient.sh. For JBossWS 4.x or later, have a look at the org.jboss.ws.cxf.jbossws-cxf-client or org.jboss.ws.native.jbossws-native-client AS7 modules. Those are aggregation modules specifying dependencies to other AS7 modules.

 

Tools

Why do I get a NullPointerException when using wstools? (legacy JAXRPC tools)

[wstools] java.lang.NullPointerException
[wstools]     at java.lang.System.arraycopy(Native Method)
[wstools]     at org.apache.xerces.impl.xs.XSModelImpl.getAnnotations(Unknown Source)
[wstools]     at org.jboss.ws.metadata.wsdl.xmlschema.WSSchemaUtils.copyXSModel(WSSchemaUtils.java:737)
[wstools]     at org.jboss.ws.tools.JavaToXSD.parseSchema(JavaToXSD.java:201)
[wstools]     at org.jboss.ws.metadata.wsdl.WSDL11Reader.processTypes(WSDL11Reader.java:227)
[wstools]     at org.jboss.ws.metadata.wsdl.WSDL11Reader.processDefinition(WSDL11Reader.java:118)
[wstools]     at org.jboss.ws.metadata.wsdl.WSDLDefinitionsFactory.parse(WSDLDefinitionsFactory.java:145)
[wstools]     at org.jboss.ws.tools.WSDLToJava.convertWSDL2Java(WSDLToJava.java:121)
[wstools]     at org.jboss.ws.tools.helpers.ToolsHelper.handleWSDLToJavaGeneration(ToolsHelper.java:323)
[wstools]     at org.jboss.ws.tools.WSTools.process(WSTools.java:138)
[wstools]     at org.jboss.ws.tools.WSTools.generate(WSTools.java:120)
[wstools]     at org.jboss.ws.tools.ant.wstools.execute(wstools.java:103)
 ...

This is a xerces bug that was fixed in 2.7.0. Make sure you're using at least the 2.7.0 xerces jars in your ANT_HOME/lib directory.

 

How can I configure RPC parameter names?

Parameter and result names can be configured using the JSR-181 @WebParam and @WebResult annotations:

@WebMethod(operationName = "SecurePing")
@WebResult(name = "Result")
public String ping(
    @WebParam(name = "Ping") PingDocument p, 
    @WebParam(name = "SecHeader", header = true) SecurityHeader secHdr)
{
   log.info("ping: " + p + "," + secHdr);
   return "pong";
}

Customizing WSDL Schema Generation

Both JBossWS runtime and WSProvide tool use JAXB (concretely JAXBRIContext.generateSchema() method) for WSDL schema generation thus the only possible way of schema customization is through javax.xml.bind.annotation.* annotations.

Therefore users that want to customize WSDL schema generation process should be familiar with these annotations. We suggest everyone interested in to take a look to Java Types To XML chapter of JAXB specification.

In the case user want to customize the generated WSDL schema and he is not able to achieve that through javax.xml.bind.annotation.* annotations he have always the possibility to customize the generated WSDL contract and force JBossWS runtime to use it via javax.jws.WebService.wsdlLocation annotation field.

 

Customizing WSDL to Java Mapping

There are many customizations available when generating Java artifacts from WSDL. See https://jax-ws.dev.java.net/jax-ws-20-fcs/docs/customizations.html for available customizations.

Others

How to force JBossWS to generate SOAP messages with xml declaration

Since 3.0.2 (Native)

JBossWS generates no processing instructions in messages by default. However there are some SOAP stacks that require xml declaration to be present in exchanged SOAP messages. It is possible to turn this feature on for whole JBossWS client or server instance by specifying the following JVM property on the java command line:

-Djavax.xml.soap.write-xml-declaration=true