|
|
The service definition must be supplied as an XML file and referenced in the
web.xml file for a Java servlet application (see Service Configuration for details). Usually this service
definition is very simple, as in the following example:
<service name="quake">
<schema>SeismicSchema.xsd</schema>
<wsdl-uri>http://seismic.sosnoski.com/wsdl</wsdl-uri>
<handler-class>com.sosnoski.seismic.jibxsoap.QuakeBase</handler-class>
<operation method="process"/>
</service>
This defines a service named quake linked to the class
com.sosnoski.seismic.jibxsoap.QuakeBase. A single operation is
defined as linked to the method process() within that class, with
the operation name by default the same as the method name. When the service is
invoked, the body of the SOAP request is unmarshalled using the established
JiBX binding definitions. The type of the unmarshalled object is used to
determine the operation requested, by matching the object type to the parameters
types of the defined operations (so if multiple operations are defined, each
must take a different type of parameter). The return type of each operation
method must be a type with a defined mapping. When an operation is invoked with
a request, the object returned by the corresponding method call is marshalled
as the body of the SOAP response.
The above service definition also includes optional components used in
generating the WSDL service description, consisting in this case of the schema
definition for the XML data to be exchanged and the namespace URI for the WSDL
definitions.
A number of other optional components can be used for
special purposes. 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: [schema], [wsdl-uri], handler-class,
[filter-class]*, operation+ (one handler-class child, zero or more filter-class
children, one or more operation children) |
| schema |
Optional path to schema definition for XML data exchanged by service.
This may be either a path relative to the web application WEB-INF directory, an
absolute path on the file system, or an absolute URL. If not supplied, WSDL will
not be generated for the service.
Children: none (text content only) |
| wsdl-uri |
Namespace URI for WSDL definitions. This is required if WSDL generation
is to be supported, but is optional and unused otherwise.
Children: none (text content only) |
| handler-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) |
| filter-class |
Optional filter class definition. Each filter class must implement the
org.jibx.soap.IMessageFilter interface. An instance of the filter
class will be created for each context and called as part of the request and
response handling. Since a separate filter class instance is created for each
context these do not need to be threadsafe - only one thread will call any given
filter instance at a time.
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) |
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. The definition may also include a list of handlers used with
request and response messages.
Each service definition may optionally include the necessary information to
support WSDL generation, which requires at least a schema definition for the
elements used as request and response bodies (supplied as a path in the
schema child element) and a WSDL namespace URI (in the wsdl-uri
child element). If either of these child elements is missing,
WSDL generation will not be supported for the service and requests for the WSDL
will return a 404 Not Found response.
Three names are associated with the WSDL definition of a service: The service
name, the binding name, and the port name. By default these are all generated,
based either on a supplied base name (from the base-name attribute) or on
the file name of the supplied schema definition (that is, what's left after
stripping off leading directory paths and trailing extensions), but they may be
overridden by using attributes of the service element. The WSDL
generation also requires a namespace URI; this defaults to the access path of
the service, but can also be overridden by using an attribute.
Attributes
| name |
Base name used to derive other names for this service. If supplied, this
replaces the schema file name as the base for generating other names used in the
WSDL for the service. |
| service-name |
Optional name to be used for this service in generated WSDL. If not
supplied, a name is generated by appending "Service" to the base name. |
| binding-name |
Optional name to be used for the service binding in generated WSDL. If
not supplied, a name is generated by appending "Binding" to the base
name. |
| port-type-name |
Optional name to be used for the service port type in generated WSDL. If
not supplied, a name is generated by appending "Interface" to the base name. |
| port-name |
Optional name to be used for the service port in generated WSDL. If not
supplied, the base name is used as the port name. |
| jibx-binding |
Optional name for the JiBX binding used for the request and response
messages exchanged by operations. This is only needed if multiple bindings are
defined for some of the classes used for requests or responses. |
| indent |
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. |
The operation element defines a single operation for a service. Each
operation uses an associated method within the handler-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 JibxSoap the input
message element name always determines the particular operation to be performed.
JibxSoap actually finds the input message element name corresponding to each
operation by doing a reverse lookup within the class mappings given in the
binding definition specified by the service element. 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.
Most of the operation information is generated by default, with only the
method name required.
Attributes
| method |
Method name for this operation, the only required attribute. This must
be a public method within the handler-class specified by the
service element. |
| soap-action |
Optional SOAPAction HTTP header value for this operation. If a SOAPAction
header is present on a request it must match the operation associated with the
message body or an error is returned. By default, SOAPAction values are left
empty and are not included in generated WSDL, since they effectively add no
useful information for doc/lit services. |
| operation-name |
Optional name for this operation used in generated WSDL. By default, the
operation name is the same as the method name. |
|