|
|
The service definition contains details of the methods that are to be exposed as web service operations, and provides
customization options for aspects such as the formatting of the XML, adding header handlers, adding custom fault
handlers etc.
Unless you're configuring your service using Spring, the service definition must be supplied
as an XML file. This file
is referenced in the web.xml file for a WsServlet,
or as a command line argument to the TcpServer. Usually
this service definition is very simple, as in the following example:
<service name="quake">
<service-class>com.sosnoski.seismic.server.QuakeBase</service-class>
<operation method="process"/>
</service>
This defines a service named quake linked to the class com.sosnoski.seismic.server.QuakeBase.
A single operation is defined as linked to the method process() within that class . By default, it is assumed that a single JiBX binding definition contains
the JiBX bindings for the method parameter and return values. JiBX/WS will automatically detect and use those bindings.
When the service is invoked, the body of the input message is unmarshalled. The type of the unmarshalled object is used to
determine the operation requested, by matching the object type to the parameter types of the defined operations (so if
multiple operations are defined, each must take a different type of parameter). When an operation is invoked, the object
returned by the corresponding method call is marshalled as the body of the output message.
A number of other optional components can be used. The full list of elements used in the
service definition is supplied below, along with the list of possible child elements for each and linked details for the
elements with complex content. Most child elements are optional and only used when necessary to change default behavior;
all are ordered.
Elements
| service |
The root element of the service definition. See <service> for the list of attributes
and other additional information.
Children: service-class, operation+,
[jibx-binding], [jibx-in-binding], [jibx-out-binding], [handler-class]*,
[output-completion-listener-class], [service-exception-handler-class],
[fault], [http-servlet-options] elements, and attributes.
(one service-class child, one or more operation children, zero or one jibx-binding child,
zero or one jibx-in-binding child, zero or one jibx-out-binding child,
zero or more handler-class children,
zero or one output-completion-listener-class child, zero or one service-exception-handler-class child,
zero or one fault child, zero or one http-servlet-options child)
|
| service-class |
Required fully qualified name of class used to process requests for this service. All operations defined for
the service must be implemented by methods of this class.
Children: none (text content only)
|
| operation |
Definition of an operation supported by this service. See <operation> for the list
of attributes and other additional information.
Children: [input-class], [output-class]
|
| input-class |
Optional class of parameter associated with an operation method. Normally this is obtained by reflection
directly from the method information. It can be overridden using this child element to set a more-specific type than
that used in the method signature (a particular class that's expected to be used for a java.lang.Object
parameter, for instance).
Children: none (text content only)
|
| output-class |
Optional class of result associated with an operation method. Normally this is obtained by reflection directly
from the method information. It can be overridden using this child element to set a more-specific type than that used
in the method signature (a particular class that's expected to be returned for a java.lang.Object result,
for instance).
Children: none (text content only)
|
| jibx-binding |
Optional element to set the JiBX binding factory to be used for the input and output messages. This is not
normally required, since JiBX/WS will automatically discover the JiBX binding factory based on the Java class of
either the input parameter or return type of the operations. Use this element if you have multiple bindings for
these classes, and/or
need to set a specific binding. Setting jibx-binding is equivalent to setting both the jibx-in-binding
and jibx-out-binding elements to the same value.
Children: none (attributes only)
|
| jibx-in-binding |
Optional element to set the JiBX binding factory to be used for the input message. This is not
normally required, since JiBX/WS will automatically deduce the JiBX binding factory based on the Java class of
either the input parameter or return type of the operations. Use this element if you have need to set a specific
binding for the input message. See also jibx-binding and jibx-out-binding.
Children: none (attributes only)
|
| jibx-out-binding |
Optional element to set the JiBX binding factory to be used for the output message. This is not
normally required, since JiBX/WS will automatically deduce the JiBX binding factory based on the Java class of
either the input parameter or return type of the operations. Use this element if you have need to set a specific
binding for the output message. See also jibx-binding and jibx-in-binding.
Children: none (attributes only)
|
| handler-class |
Optional handler class definition for adding handlers to a service, for example
SOAP header handlers.
Children: [constructor-arg]*
|
| constructor-arg |
Optional constructor arguments to handler class
definition.
Children: none (attributes only)
|
| output-completion-listener-class |
Optional class to be called after JiBX/WS has completed sending the output message.
The class must implement org.jibx.ws.transport.OutputCompletionListener. See
interceptor example.
Children: none (text content only)
|
| service-exception-handler-class |
Optional class that overrides the default behavior when the service class throws an exception, or an error
occurs in the handling of the message. For the SOAP protocol, the default behavior is to
return a SOAP fault. For POX, the default behavior is to throw a runtime exception.
The class must extend org.jibx.ws.server.ServiceExceptionHandler. See custom exception handling example.
Children: none (text content only)
|
| fault |
Optional settings for protocol specific fault handling. See <fault> for the list of
attributes and other additional information.
Children: none (attributes only)
|
| wsdl |
Optional settings for exposing WSDL. See <wsdl> for the list of
attributes and other additional information.
Children: none (attributes only)
|
| http-servlet-options |
Optional definition of HTTP Servlet specific options.
Children: [input-stream-interceptor], [output-stream-interceptor]
(an optional input-stream-interceptor child, and an optional output-stream-interceptor child).
|
| input-stream-interceptor |
Optional stream interceptor definition for intercepting the input stream
of the HTTP servlet request. See
interceptor example.
Children: [constructor-arg]*
(zero or more constructor-arg children).
|
| output-stream-interceptor |
Optional stream interceptor definition for intercepting the output stream
of the HTTP servlet response. See
interceptor example.
Children: [constructor-arg]*
(zero or more constructor-arg children).
|
| constructor-arg |
Optional constructor arguments to stream-interceptor
definition (either input-stream-interceptor or output-stream-interceptor).
Children: none (attributes only)
|
The service element is the root element of the service definition document. The core of the service
definition is the list of operations supported by the service, which are defined by operation
child elements.
Attributes
| indent |
Optional number of spaces to use in indenting output XML. The default is to suppress all indentation and generate XML
with no added spaces or line breaks.
|
| protocol |
Optionally specifies the protocol for the service to use. Protocols currently supported are
POX and SOAP1.1. Defaults to SOAP1.1.
|
The operation element defines a single operation for a service. Each operation uses an associated method
within the service-class specified by the service element. Each operation method
must take a single input parameter and return a result object.
With the doc/lit style of web services supported by JiBX/WS the input message element name always determines the
particular operation to be performed. JiBX/WS actually finds the input message element name corresponding to each
operation by doing a reverse lookup within the class mappings given in the JiBX binding definition. The binding
definition can only associate one type of object with an element, so there's a fixed linkage between the element name
and the object type. This means that the type of the input parameter used for each operation method within a service
must be unique.
Attributes
| method |
Method name for this operation. This must be a public method within the service-class
specified by the service element.
|
The handler-class element adds handlers to a service. Each handler
class must implement either the org.jibx.ws.io.handler.InHandler
or org.jibx.ws.io.handler.OutHandler
interface (dependent on whether it is for input or output messages). An instance of the handler
class will be created for each message exchange context and called as part of the input or
output handling. Since a separate handler class instance is created for each context these do not need to be
threadsafe - only one thread will call any given handler instance at a time. However the handlers do need
to be serially reusable. Currently, the only scope in which handlers are valid is for SOAP headers.
Attributes
| class |
Specifies the Java class of the handler. This class must implement either the org.jibx.ws.io.handler.InHandler
or org.jibx.ws.io.handler.OutHandler interface. The class may optionally be constructed with arguments of type java.lang.String.
See the constructor-arg element.
|
The constructor-arg element defines arguments to be passed to the construction of a handler-class. The handler-class must have a constructor containing the same number of
arguments, and these arguments must be of type java.lang.String.
Attributes
| value |
The value of the constructor argument.
|
The fault element contains settings for protocol specific fault handling (eg. SOAP fault).
Attributes
| include-stack-trace |
If set to true, a stack trace will be included with the fault details. Optional. Defaults to false.
|
The wsdl element contains settings for configuring the service to returning a WSDL definition.
The service's WSDL definition will be returned on HTTP GET requests to the service URL, suffixed with "?wsdl".
For an example see the seismic example.
Attributes
| file |
Set to the path of the WSDL file to be returned, for example "/WEB-INF/myService.wsdl"
|
| transformLocation |
If set to true, the location of services defined in the WSDL are transformed, based on the request URL.
WSDL service locations defined as absolute URLs are modified to match the scheme, server name
and server port of the incoming WSDL request.
Service locations that are relative URLs starting with a "/", are prefixed by
scheme://serverName:serverPort, where scheme, serverName and serverPort
are obtained from the WSDL request.
For example, assuming the WSDL request is http://foo.com/bar?wsdl on port 80:
- A WSDL service location of /bar/service would be transformed to http://foo.com:80/bar/service
- A WSDL service location of http://localhost/bar/service2 would be transformed to http://foo.com:80/bar/service2
Defaults to false.
|
The optional input-stream-interceptor and output-stream-interceptor elements add interceptors to allow
input streams and output streams to be intercepted. These interceptors are only useful in the limited cases where you
need access to the raw messages. For most cases, such as logging or validation, the XML stream interceptors are
preferred. These will be implemented in a future release.
An instance of the interceptor class will be created for each message exchange context and invoked at the appropriate
point in the processing of a message. Since a separate interceptor class instance is created for each context these do not need to be
threadsafe - only one thread will call any given interceptor instance at a time. However the interceptors do need
to be serially reusable. The types of interceptor are:
| org.jibx.ws.transport.interceptor.InputStreamInterceptor |
Intercepts the InputStream at the transport level. |
| org.jibx.ws.transport.interceptor.OutputStreamInterceptor |
Intercepts the OutputStream at the transport level. |
Attributes
| class |
Specifies the Java class of the interceptor. This class must implement either the org.jibx.ws.transport.interceptor.InputStreamInterceptor
or org.jibx.ws.transport.interceptor.OutputStreamInterceptor as appropriate. The class may optionally be constructed with arguments of type java.lang.String
(see constructor-arg).
|
The optional constructor-arg element defines arguments to be passed to the construction of a stream-interceptor. The stream-interceptor must have a constructor containing the same number of
arguments, and these arguments must be of type java.lang.String.
Attributes
| value |
The value of the constructor argument.
|
|