This section of the documentation will focus on the programming
model for both developing and publishing a web service endpoint, and
writing a web service client. A web service endpoint is the
implementation of a web service. A web service client is an
application that accesses a web service.
When developing a web service endpoint, a developer may
either start from a Java endpoint implementation class or from a
WSDL file. A WSDL (Web Services Description Language) document
describes the contract between the web service endpoint and the
client. A WSDL document may include and/or import XML schema files
used to describe the data types used by the web service. When
starting from a Java class, the tools generate any portable
artifacts as mandated by the spec. When starting from a WSDL file
and schemas, the tools generate a service endpoint
interface.
There is a trade-off when starting from a Java class or from
a WSDL file. If you start from a Java class, you can make sure
that the endpoint implementation class has the desirable Java data
types, but the developer has less control of the generated XML
schema. When starting from a WSDL file and schema, the developer
has total control over what XML schema is used, but has less
control over what the generated service endpoint and the classes
it uses will contain.
1.3.1.1. Starting from Java
The basic process for deploying a web service from a
Java class consists of two steps.
Generate portable artifacts.
Create a WAR file to deploy
1.3.1.2. Generate Portable Artifacts
Portable artifacts generated by Eclipse Implementation of XML Web Services 4.0.0
include zero or more JavaBean classes to aide in the
marshaling of method invocations and responses, as well as
service-specific exceptions.
In document/literal wrapped mode, two JavaBeans are
generated for each operation in the web service. One bean is
for invoking the other for the response. In all modes
(rpc/literal and both document/literal modes), one JavaBean is
generated for each service-specific exception.
When starting from Java the developer must provide the
Jakarta XML Web Services tools with a valid endpoint implementation class. This
implementation class is the class that implements the desired
web service. Jakarta XML Web Services has a number of restrictions on endpoint
implementation classes. A valid endpoint implementation class
must meet the following requirements:
It must carry a
jakarta.jws.WebService annotation (see JSR 181).
Any of its methods may
carry a jakarta.jws.WebMethod annotation (see
7.5.2).
All of its methods may
throw java.rmi.RemoteException in addition to any
service-specific exceptions.
All method parameters and return types
must be compatible with the Jakarta XML Binding
2.0 Java to XML Schema mapping definition.
A method parameter or return value type
must not implement the
java.rmi.Remote interface either directly or
indirectly.
Here is an example of a a simple endpoint implementation
class samples/fromjava/src/fromjava/server/AddNumbersImpl.java
from the fromjava
sample:
If you are familiar with JAX-RPC 1.1, you will notice
that this implementation class does not implement a service
endpoint interface. In Eclipse Implementation of XML Web Services 4.0.0 a service
endpoint interface is no longer required.
When starting from a Java endpoint implementation class,
it is recommended that the portable artifacts be generated
from source using annotationProcessing. This because the
Jakarta XML Web Services tools will then have full access to the source code and
will be able to utilize parameter names that are otherwise not
available through the Java reflection APIs. If the source for
the endpoint implementation class is not available, the
portable artifacts can be generated using
wscompile. Here is a sample
annotationProcessing Ant task from the samples:
More information about the annotationProcessing Ant
task can be found annotationProcessing Ant Task. If this task is run on the
fromjava sample, the output would include:
The AddNumbersImplService.wsdl
file
describes the web service. The
schema1.xsd
file is imported by the
AddNumbersImplService.wsdl
and contains
the datatypes used by the web service. The
AddNumbers.class
/AddNumbers.java
files contain the a bean used by a Jakarta XML Binding to marshall/unmarshall
the addNumbers
request. The
AddNumbersExceptionBean.class
/AddNumbersExceptionBean.java
file is a bean used by Jakarta XML Binding to marshall the contents of the
AddNumbersException
class. The
AddNumbersResponse.class
/AddNumbersResponse.java
files represent the response bean used by Jakarta XML Binding to
marshall/unmarshall the addNumbers
response.
1.3.1.3. Create a WAR file to deploy
Creating a WAR file is nothing more than packaging the
service endpoint interface (if there is one), service endpoint
implementation, Java classes used by the endpoint
implementation and a deployment descriptor in WAR format. For
the fromjava sample the AddNumbersImpl
and
AddNumbersException
classes in the
fromjava.server package, and the deployment
descriptor are bundled together to make a raw WAR file. To
learn more about creating a WAR file and the deployment
descriptor, see WAR File Packaging. The deployment descriptor used in
fromjava sample is given below and
can be found samples/fromjava/etc/sun-jaxws.xml
:
The attributes of the
<endpoint>
element are described
below:
name is simply an identifier for this
endpoint
implementation is used to specify the endpoint
implementation class
urlpattern is used to URL pattern used to access
this endpoint.
The structure of the raw WAR file is shown below:
The WAR file created can now be published on a
Eclipse Implementation of XML Web Services enabled servlet container such as
the Sun
Java System Application Server Platform Edition
8.2
1.3.1.4. Starting from a WSDL File
The basic process for deploying a web service when
starting from a WSDL document consists of the following four
steps:
Generate a service endpoint interface.
Implement the service endpoint interface.
Create a WAR file to deploy.
1.3.1.5. Generate a Service Endpoint Interface
This step involves compiling or importing the WSDL file
to generate a service endpoint interface and value classes
mapped from imported XML schemas.
Below is a sample wsimport Ant
target:
Its commandline equivalent is:
Lets look at the excerpt of samples/fromwsdl/etc/AddNumbers.wsdl
from the sample fromwsdl:
The generated service endpoint interface looks as
follows:
The generated service endpoint interface has annotations
that can be used by the future versions of Jakarta XML Web Services to do
dynamic binding and serialization/deserialization at runtime.
Alternatively this service endpoint interface can be used to
generate a WSDL and schema file. Please note that
round-tripping is not guaranteed in this case. So the
generated WSDL file and schema may not be the same as the one
the service endpoint interface was generated from.
1.3.1.6. Implement the Service Endpoint Interface
The next thing to do will be to provide the
implementation of the service endpoint interface generated in
the previous step. When you implement the service endpoint
interface it is necessary to provide a
@WebService
annotation on the
implementation class with a endpointInteface element
specifying the qualified name of the endpoint interface class.
Let's look at the implementation class samples/fromwsdl/src/fromwsdl/server/AddNumbersImpl.java
from the sample application
fromwsdl:
This step is similar to the one described above in Create a WAR file to deploy .
Here the service endpoint interface implementation class
from previous step, together with a deployment descriptor file
sun-jaxws.xml, and web.xml
should be
bundled together with the service endpoint interface, value
classes generated in the first step mentioned in Generate a Service Endpoint Interface.
Let's look at samples/fromwsdl/etc/sun-jaxws.xml
from the sample application
fromwsdl:
It defines the deployment-related configuration
information for the fromwsdl
endpoint. You will notice that this deployment descriptor
contains additional attributes than the deployment descriptor
described in Create a WAR file to deploy. The interface attribute
references the service endpoint interface generated in step 1.
The wsdl attribute also points at the WSDL that was imported
by wsimport. The service attribute
references which service in the WSDL this endpoint is from and
the port is the name of the port in that service for this
endpoint.
To learn more about creating a WAR file and the
deployment descriptor, see WAR File Packaging.
The WAR file created can now be published on a
Eclipse Implementation of XML Web Services enabled servlet container such as
the Sun
Java System Application Server Platform Edition
8.2
1.3.1.8. Java SE Endpoints
Endpoints can be created and published programmatically
using jakarta.xml.ws.Endpoint
API in J2SE. To
learn more about these endpoints, see Endpoint API.
A client application can access a remote web service
endpoint in one of two ways: port and dispatch.
In this approach client side invokes Web services via a
dynamic proxy. The proxies for the Web Service are created
from the generated Service and service endpoint interfaces.
Once the proxies are created. the client application can
invoke methods on those proxies just like a standard
implementation of those interfaces. The sections below
describe this process more detail.
1.3.2.2. Generate Client Artifacts
The wsimport tool is used to generate
the service endpoint interface and the service interface
classes. Below is the sample wsimport Ant
target:
The command line equivalent of this Ant target
is:
For more details see the wsimport documentation.
Here is the excerpt from samples/fromwsdl/src/fromwsdl/client/AddNumbersClient.java
in the fromjava sample
application:
The Dispatch
API is intended for
advanced XML developers who prefer using XML constructs at the
java.lang.transform.Source
or
jakarta.xml.soap.SOAPMessage
level. For added
convenience use of Dispatch
with Jakarta XML Binding data
binding object is supported. With the
XML/HTTP
binding a
jakarta.activation.DataSource
can also be
used. The Dispatch
APIs can be used in both
Message
and Payload
modes. The Dispatch
API client with an
XML/HTTP
binding can be used with REST Web
Services. Please see the restful sample program for more
information.
For more information on Dispatch
in
Eclipse Implementation of XML Web Services 4.0.0 please refer to Dispatch.