[jboss-user] [JBoss Web Services] - JBossWS - FAQ
Alessio Soldano
do-not-reply at jboss.com
Wed Dec 21 11:43:50 EST 2011
Alessio Soldano [http://community.jboss.org/people/asoldano] modified the document:
"JBossWS - FAQ"
To view the document, visit: http://community.jboss.org/docs/DOC-13646
--------------------------------------------------------------
**
#General General
***
#Which_version_of_App_Server_is_JBossWS_supported_for Which version of App Server is JBossWS supported for?
***
#Why_are_my_forum_posts_not_answered_more_quickly Why are my forum posts not answered more quickly?
***
#Are_there_any_samples_I_can_look_at Are there any samples I can look at?
***
#What_are_the_advantages_of_JAXWS_over_JAXRPC What are the advantages of JAX-WS over JAX-RPC?
**
#Development Development
***
#What_do_I_do_if_I_think_there_is_a_bug What do I do if I think there is a bug?
***
#Where_is_the_JBossWS_source_repository Where is the JBossWS source repository?
***
#How_can_I_build_and_install_the_latest How can I build and install the latest?
**
#Server Server
***
#How_does_rewriting_of_the_soap_address_in_WSDL_work How does rewriting of the soap address in WSDL work?
***
#How_do_I_know_what_endpoint_address_is_being_used How do I know what endpoint address is being used?
***
#How_to_use_JDK_JMX_JConsole_with_JBossWS How to use JDK JMX JConsole with JBossWS?
***
#Why_Im_getting_propertyname_is_not_valid_property_on_class_mypackagejaxwsPropertyname Why I'm getting "propertyname is not valid property on class mypackage.jaxws.Propertyname"?
**
#Client Client
***
#How_do_I_generate_the_required_artifacts How do I generate the required artifacts?
***
#How_can_I_leverage_the_client_deployment_model How can I leverage the client deployment model?
***
#How_can_I_setup_my_client_to_use_a_proxy How can I setup my client to use a proxy?
***
#What_client_artifacts_are_thread_safe What client artifacts are thread safe?
***
#What_client_jars_do_I_need What client jars do I need?
**
#Tools Tools
***
#Why_do_I_get_a_NullPointerException_when_using_wstools_legacy_JAXRPC_tools Why do I get a NullPointerException when using wstools? (legacy JAXRPC tools)
***
#How_can_I_configure_RPC_parameter_names How can I configure RPC parameter names?
***
#Customizing_WSDL_Schema_Generation Customizing WSDL Schema Generation
***
#Customizing_WSDL_to_Java_Mapping Customizing WSDL to Java Mapping
**
#Others Others
***
#How_to_force_JBossWS_to_generate_SOAP_messages_with_xml_declaration How to force JBossWS to generate SOAP messages with xml declaration
h2. General
h3. Which version of App Server is JBossWS supported for?
http://community.jboss.org/docs/DOC-13569 Supported Target Containers
h3. Why are my forum posts not answered more quickly?
Posts to the http://www.jboss.com/index.html?module=bb&op=viewforum&f=200 user forum will be dealt with at the community's leisure. If your business is such that you need to rely on http://www.jboss.com/services/profsupport qualified answers within a known time frame, the forum might not be your preferred support channel.
h3. Are there any samples I can look at?
Yes, samples are available from the JBossWS http://labs.jboss.com/jbossws/downloads download page.
h3. What are the advantages of JAX-WS over JAX-RPC?
http://community.jboss.org/docs/DOC-13568 JAX-WS_vs_JAX-RPC
h2. Development
h3. What do I do if I think there is a bug?
* Check if it works with the http://community.jboss.org/docs/DOC-13547 latest sources.
* Checkout the http://jira.jboss.com/jira/browse/JBWS?report=com.atlassian.jira.plugin.system.project:roadmap-panel Road Map if you are using the latest release or the http://jira.jboss.com/jira/browse/JBWS?report=com.atlassian.jira.plugin.system.project:changelog-panel Change Log if you are using another one.
* Finally, if your bug hasn't been reported yet, please create a http://jira.jboss.com/jira/browse/JBWS?report=com.atlassian.jira.plugin.system.project:openissues-panel 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.
h3. Where is the JBossWS source repository?
Please refer to http://community.jboss.org/docs/DOC-13526 Subversion.
h3. How can I build and install the latest?
Please refer to the development guide: http://community.jboss.org/docs/DOC-13547 Building_From_Source
h2. Server
h3. How does rewriting of the soap address in WSDL work?
Please refer to the https://docs.jboss.org/author/display/JBWS/Advanced+User+Guide advanced user guide section of JBossWS 4.x or later, or to the http://community.jboss.org/docs/DOC-13972 user guide's Configuration section (previous JBossWS versions)
h3. 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 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 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" )
h3. 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 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 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.
h3. 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).
h2. Client
h3. 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 http://community.jboss.org/docs/DOC-13542 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 http://ant.apache.org/ 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 http://community.jboss.org/docs/DOC-13544 top-down development strategy in the user guide.
Finally, if you need JAX-RPC artifacts generation, please refer to the legacy JBossWS tools documentation.
h3. 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.
h3. How can I setup my client to use a proxy?
[ http://labs.jboss.com/jbossremoting/docs/guide/ch05.html 5.4.10. HTTP(S) Client Invoker - proxy and basic authentication]
h3. 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 http://cxf.apache.org/faq.html Apache CXF FAQ for further info when using JBossWS-CXF stack.
h3. What client jars do I need?
For JBossWS 3.x or previous versions, please have a look at http://community.jboss.org/docs/DOC-13529 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.
h2. Tools
h3. 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.
h3. How can I configure RPC parameter names?
Parameter and result names can be configured using the JSR-181 http://community.jboss.org/docs/DOC-13510 @WebParam and http://community.jboss.org/docs/DOC-13510 @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";
}
h3. 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.
h3. 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 https://jax-ws.dev.java.net/jax-ws-20-fcs/docs/customizations.html for available customizations.
h2. Others
h3. 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
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-13646]
Create a new document in JBoss Web Services at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2044]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-user/attachments/20111221/1597ac4b/attachment-0001.html
More information about the jboss-user
mailing list