[[JAX_WS_JBoss_Modules_and_WS_applications]]
= JBoss Modules and WS applications

The JBoss Web Services functionalities are provided by a given set of
modules / libraries installed on WildFly, which are organized into JBoss
Modules modules. In particular the _org.jboss.as.webservices.*_ and
_org.jboss.ws.*_ modules belong to the JBossWS - WildFly integration.
Users should not need to change anything in them.

While users are of course allowed to provide their own modules for their
custom needs, below is a brief collection of suggestions and hints
around modules and webservices development on WildFly.

[[setting-module-dependencies]]
== Setting module dependencies

On WildFly the user deployment classloader does not have any visibility
over JBoss internals; so for instance you can't _directly_ use JBossWS
_implementation_ classes unless you explicitly set a dependency to the
corresponding module. As a consequence, users need to declare the module
dependencies they want to be added to their deployment.

[IMPORTANT]

The JBoss Web Services APIs are always available by default whenever the
webservices subsystem is available on AS7. So users just use them, no
need for explicit dependencies declaration for those modules.

[[using-manifest.mf]]
=== Using MANIFEST.MF

The convenient method for configuring deployment dependencies is adding
them into the MANIFEST.MF file:

....
Manifest-Version: 1.0
Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services export,foo.bar
....

Here above _org.jboss.ws.cxf.jbossws-cxf-client_ and _foo.bar_ are the
modules you want to set dependencies to; _services_ tells the modules
framework that you want to also import _META-INF/services/.._
declarations from the dependency, while _export_ exports the classes
from the module to any other module that might be depending on the
module implicitly created for your deployment.

[IMPORTANT]

When using annotations on your endpoints / handlers such as the Apache
CXF ones (@InInterceptor, @GZIP, ...) remember to add the proper module
dependency in your manifest. Otherwise your annotations are not picked
up and added to the annotation index by WildFly, resulting in them being
completely and silently ignored.

[[using-jaxb]]
==== Using JAXB

In order for successfully directly using JAXB contexts, etc. in your
client or endpoint running in-container, you need to properly setup a
JAXB implementation; that is performed setting the following dependency:

....
Dependencies: com.sun.xml.bind services export
....

[[using-apache-cxf]]
==== Using Apache CXF

In order for using Apache CXF APIs and implementation classes you need
to add a dependency to the _org.apache.cxf_ (API) module and / or
_org.apache.cxf.impl_ (implementation) module:

....
Dependencies: org.apache.cxf services
....

However, please note that would not come with any JBossWS-CXF
customizations nor additional extensions. For this reason, and generally
speaking for simplifying user configuration, a client side aggregation
module is available with all the WS dependencies users might need.

[[client-side-ws-aggregation-module]]
==== Client side WS aggregation module

Whenever you simply want to use all the JBoss Web Services
feature/functionalities, you can set a dependency to the convenient
client module.

....
Dependencies: org.jboss.ws.cxf.jbossws-cxf-client services
....

Please note the _services_ option above: that's strictly required in
order for you to get the JBossWS-CXF version of classes that are
retrieved using the _Service API_, the `org.apache.cxf.Bus` for
instance.

[IMPORTANT]

Be careful as issues because of misconfiguration here can be quite hard
to track down, because the Apache CXF behaviour would be sensibly
different.

[IMPORTANT]

The _services_ option is almost always needed when declaring
dependencies on _org.jboss.ws.cxf.jbossws-cxf-client_ and
_org.apache.cxf_ modules. The reason for this is in it affecting the
loading of classes through the _Service API_, which is what is used to
wire most of the JBossWS components as well as all Apache CXF Bus
extensions.

[[annotation-scanning]]
==== Annotation scanning

The application server uses an annotation index for detecting JAX-WS
endpoints in user deployments. When declaring WS endpoints whose class
belongs to a different module (for instance referring that in the
`web.xml` descriptor), be sure to have an `annotations` type dependency
in place. Without that, your endpoints would simply be ignored as they
won't appear as annotated classes to the webservices subsystem.

[source, java]
----
Dependencies: org.foo annotations
----

[[using-jboss-deployment-descriptor.xml]]
=== Using jboss-deployment-descriptor.xml

In some circumstances, the convenient approach of setting module
dependencies in MANIFEST.MF might not work. An example is the need for
importing/exporting specific resources from a given module dependency.
Users should hence add a jboss-deployment-structure.xml descriptor to
their deployment and set module dependencies in it.