Writing Callback Objects

Reply-To: wsrf-dev@ws.apache.org Delivered-To: mailing list wsrf-commits@ws.apache.org Received: (qmail 10175 invoked by uid 500); 18 Oct 2005 22:48:40 -0000 Delivered-To: apmail-ws-wsrf-cvs@ws.apache.org Received: (qmail 10069 invoked by uid 99); 18 Oct 2005 22:48:40 -0000 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Tue, 18 Oct 2005 15:48:36 -0700 Received: (qmail 63297 invoked by uid 65534); 18 Oct 2005 22:48:15 -0000 Message-ID: <20051018224815.63296.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r326288 - in /webservices/wsrf/trunk/src/site/content/xdocs/dev_guide: callback.xml home.xml index.xml metadata.xml service.xml wsdl_tool.xml Date: Tue, 18 Oct 2005 22:48:14 -0000 To: wsrf-cvs@ws.apache.org From: ips@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Author: ips Date: Tue Oct 18 15:48:10 2005 New Revision: 326288 URL: http://svn.apache.org/viewcvs?rev=326288&view=rev Log: minor corrections Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/callback.xml webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/callback.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/callback.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/callback.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/callback.xml Tue Oct 18 15:48:10 2005 @@ -1,128 +1,128 @@ - - - -

- Writing Callback Objects -

- -

- Introduction -

Callback objects provide a means to keep resource properties in synch with the corresponding - state in the backend managed resource. You write callback objects and register them on any - non-static resource properties. The registration of callbacks is typically done upon initialization of the - Resource class, in its init method. An example of this can be seen in - FileSystemResource. -

There are two interfaces which can be implemented when writing a Callback object. Which one you choose depends on how you would - like each ResourceProperty to behave: -

- org.apache.ws.resource.properties.ResourcePropertyCallback - Implement this interface if the resource property will - change (not static i.e. "name"), but is not modifiable externally. It provides the ability to refresh the front-end with the current state of your - backend. -
- org.apache.ws.resource.properties.SetResourcePropertyCallback - Implement this interface if the resource property is - modifiable, thus methods like insert, update and delete - may be appropriate. This interface extends ResourcePropertyCallback. -

- Implementing a ResourcePropertyCallback -

- ResourcePropertyCallback is a way for you to synchronize the front-end resource properties with the backend. The - interface defines one method: -

- ResourceProperty refreshProperty( ResourceProperty prop ); -

Notice the operation is passed a ResourceProperty. The ResourceProperty contains methods for pulling the values out of the property. You - can get an iterator, in the case of a list, or can retrieve via an index: ResourceProperty.get(i) -

The returned property will be an XmlBean type. What "type" will depend on your method description in your wsdl. If the type is a schema-defined type - (string, int etc.), XmlBeans provides objects specific to those types. In - BackupFrequencyCallback we see that BackupFrequency was an xsd:int and so the XmlBean - type is XmlInt: -

- public ResourceProperty refreshProperty(ResourceProperty prop) - { - XmlInt xInt = (XmlInt) prop.get( 0 ); - xInt.setIntValue( m_fileSystem.getBackupFrequency() ); - return prop; - } -

In the case of complex types, XmlBeans will generate a type and that is what will be passed to the operation. An example of - this in OptionsCallback: -

- public ResourceProperty refreshProperty( ResourceProperty prop ) - { - Iterator iterator = prop.iterator( ); - while ( iterator.hasNext( ) ) - { - OptionsDocument.Options o = (OptionsDocument.Options) iterator.next( ); - clearOptionsFromProperty( o ); - - //add current options... - List options = m_fileSystem.getOptions( ); - for ( int i = 0; i options.size( ); i++ ) - { - o.addOption( options.get( i ).toString( ) ); - } - } - - return prop; - } -

In both cases the objects (XmlInt and Options) all extend XmlObject as a common class, - however it is useful to utilize the defined class' operations directly. -

Once you have a handle on the passed-in object, you will need to set the equivalent value, from the current state of your backend, on the passed-in object. -

The refreshProperty method is called by Apache WSRF before servicing GetResourceProperty, GetMultipleResourceProperties and QueryResourceProperties requests. -

- Implementing the SetResourcePropertyCallback -

- SetResourcePropertyCallback is a way for the backend to be changed via requests to the front-end resource properties. - The SetResourcePropertyCallback interface defines three methods: -

- void deleteProperty( QName propQName ); -void insertProperty( Object[] prop ); -void updateProperty( Object[] prop ); -

The operations will follow the same semantics as are defined in the specification and will be restricted to - the bounds defined by the resource properties document schema. If you define an element with a maxOccurs="1", - and attempt to add (insertProperty) another item to it, Apache WSRF will generate a fault. -

- CommentCallback illustrates how these methods may be implemented:

- public void deleteProperty( QName propQName ) - { - return; // no need to implement - Apache WSRF will never call delete for a property whose minOccurs != 0 - } - - public void insertProperty( Object[] propElems ) - { - // Comment prop has cardinality of 1, so passed array will always have exactly one element - XmlString xString = (XmlString) propElems[0]; - m_fileSystem.setComment( xString.getStringValue() ); - } - - public void updateProperty( Object[] propElems ) - { - insertProperty( prop ); - } - -

Notice that the deleteProperty method does nothing since the implementor knew that the method - would never be called since the schema forbids it. The updateProperty simply hands-off to the - insertProperty since the implementor knew that an update on the backend is the same as an insert. - The insertProperty method is the workhorse method; it takes an array of property elements and - updates the corresponding backend property.

- Registering a Callback -

Once you've written your callback objects you will need to register them with the resource properties. - This is done in the init method of your Resource implementation class. See the FileSystemResource - for an example.

- - + + + +

+ Writing Callback Objects +

+ +

+ Introduction +

Callback objects provide a means to keep resource properties in synch with the corresponding + state in the backend managed resource. You write callback objects and register them on any + non-static resource properties. The registration of callbacks is typically done upon initialization of the + Resource class, in its init method. An example of this can be seen in + FileSystemResource. +

There are two interfaces which can be implemented when writing a Callback object. Which one you choose depends on how you would + like each ResourceProperty to behave: +

+ org.apache.ws.resource.properties.ResourcePropertyCallback - Implement this interface if the resource property's value + may change (not static - e.g. "name"), but is not modifiable externally. It provides the ability to refresh the front-end with the current state of your backend. +
+ org.apache.ws.resource.properties.SetResourcePropertyCallback - Implement this interface if the resource property is + modifiable, thus methods like insert, update and delete + may be appropriate. This interface extends ResourcePropertyCallback. +

+ +

+ Implementing a ResourcePropertyCallback +

+ ResourcePropertyCallback is a way for you to synchronize the front-end resource properties with the backend. The + interface defines one method: +

+ ResourceProperty refreshProperty( ResourceProperty prop ); +

Notice the operation is passed a ResourceProperty. The ResourceProperty contains methods for pulling the individual elements out of the property. You can either get an iterator of the property elements or retrieve a specific element via an index: ResourceProperty.get(i) +

The returned property will be an XmlBean type. What "type" will depend on your method description in your WSDL. If the type is a schema-defined type + (string, int etc.), XmlBeans provides objects specific to those types. In + BackupFrequencyCallback we see that BackupFrequency was an xsd:int and so the XmlBean + type is XmlInt: +

+ public ResourceProperty refreshProperty(ResourceProperty prop) + { + XmlInt xInt = (XmlInt) prop.get( 0 ); + xInt.setIntValue( m_fileSystem.getBackupFrequency() ); + return prop; + } +

In the case of complex types, XmlBeans will generate a type and that is what will be passed to the operation. An example of + this in OptionsCallback: +

+ public ResourceProperty refreshProperty( ResourceProperty prop ) + { + Iterator iterator = prop.iterator( ); + while ( iterator.hasNext( ) ) + { + OptionsDocument.Options o = (OptionsDocument.Options) iterator.next( ); + clearOptionsFromProperty( o ); + + //add current options... + List options = m_fileSystem.getOptions( ); + for ( int i = 0; i options.size( ); i++ ) + { + o.addOption( options.get( i ).toString( ) ); + } + } + + return prop; + } +

In both cases the objects (XmlInt and Options) all extend XmlObject as a common class, + however it is useful to utilize the defined class' operations directly. +

Once you have a handle on the passed-in object, you will need to set the equivalent value, from the current state of your backend, on the passed-in object. +

The refreshProperty method is called by Apache WSRF before servicing GetResourceProperty, GetMultipleResourceProperties and QueryResourceProperties requests to ensure that the property element(s) returned to the client are up-to-date. +

+ +

+ Implementing a SetResourcePropertyCallback +

+ SetResourcePropertyCallback is a way for the backend state to be updated via SetResourceProperties requests to the front-end resource. + The SetResourcePropertyCallback interface defines three methods: +

+ void deleteProperty( QName propQName ); +void insertProperty( Object[] propElems ); +void updateProperty( Object[] propElems ); +

The operations will follow the same semantics as are defined in the specification and will be restricted to + the bounds defined by the resource properties document schema. If you define an element with a maxOccurs="1", + and attempt to add (insertProperty) another item to it, Apache WSRF will generate a fault. +

+ CommentCallback illustrates how these methods may be implemented:

+ public void deleteProperty( QName propQName ) + { + return; // no need to implement - Apache WSRF will never call delete for a property whose minOccurs != 0 + } + + public void insertProperty( Object[] propElems ) + { + // Comment prop has cardinality of 1, so passed array will always have exactly one element + XmlString xString = (XmlString) propElems[0]; + m_fileSystem.setComment( xString.getStringValue() ); + } + + public void updateProperty( Object[] propElems ) + { + insertProperty( prop ); + } + +

Notice that the deleteProperty method does nothing since the implementor knew that the method + would never be called since the schema forbids it. The updateProperty simply hands-off to the + insertProperty since the implementor knew that an update on the backend is the same as an insert. + The insertProperty method is the workhorse method; it takes an array of property elements and + updates the corresponding backend property.

+ Registering a Callback +

Once you've written your callback objects you will need to register them with the resource properties. + This is typically done in the init method of your Resource implementation class. See the FileSystemResource + for an example.

+ + Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml Tue Oct 18 15:48:10 2005 @@ -1,56 +1,53 @@ - - - -

- Writing a Home class -

- -

- Introduction -

The home class is used to lookup the resource instance. It can act as a factory for creating instances upon request, or build all instances. It is meant - to be the entry point for locating a resource instance. -

- If your service is a singleton and only requires a single resource instance, see the Creating a Singleton Service section. -

If you use the Wsdl2Java tool, the home class is automatically generated, but will need to modified to create instances of your resource. This section will - describe how to write a home class for your resource. Initially, you should model your resource off of the included FilesystemHome example - to ensure that you write a valid home class for your resource. -

- Class Declaration -

The generated home class extends AbstractResourceHome. Extending AbstractResourceHome - provides services for caching instances and looking them up. It also ensures - that the correct interfaces are implemented so that Apache WSRF can interact with your home. -

The FileSystemHome class extends AbstractResourceHome and implements Serializable:

- public class FileSystemHome - extends AbstractResourceHome - implements Serializable - Many of the operations in the AbstractResourceHome may be overridden in your Home - class, if you have a need to modfify or extend the base class' functionality. -

- Operations -

If you extend AbstractResourceHome, the only required operation you will need to implement is:

- public void init() -

The init() operation can be used to initialize any instances at startup. - In the FileSystem example, the init() method is used to create and add two resource instances:

- public void init() throws Exception - { - super.init(); - add( createInstance( LVOL1_ID ) ); - add( createInstance( LVOL2_ID ) ); - } -

The createInstance() method:

Creates an instance of the resource.
Sets an endpoint reference on the resource.
Calls init() on the resource.

- If you choose to not use the createInstance() method (e.g. if you have a non-empty constructor), then you must manually set the EPR then call - the init() method on the resource. The generated home class contains a utility method from the AbstractResourceHome that can be used - to build an EPR. -

- - + + + +

+ Writing a Home class +

+ +

+ Introduction +

The home class is used to lookup resource instances. It can act as a factory for creating instances upon request, or build all instances. It is meant + to be the entry point for locating a resource instance. +

+ If your service is a singleton and only requires a single resource instance, see the Creating a Singleton Service section. +

If you use the Wsdl2Java tool, the home class is automatically generated, but will may be modified to create instances of your resource. This section will + describe how to write a home class for your resource. Initially, you should model your resource off of the included FilesystemHome example + to ensure that you write a valid home class for your resource. +

+ Class Declaration +

The generated home class extends AbstractResourceHome. Extending AbstractResourceHome + provides services for caching instances and looking them up. It also ensures + that the correct interfaces are implemented so that Apache WSRF can interact with your home. +

The FileSystemHome class extends AbstractResourceHome and implements Serializable:

+ public class FileSystemHome + extends AbstractResourceHome + implements Serializable + Many of the operations in the AbstractResourceHome may be overridden in your Home + class, if you have a need to modify or extend the base functionality. +

+ Operations +

If you extend AbstractResourceHome, the only required operation you may wish to override is:

+ public void init() +

The init() operation can be used to initialize any instances at startup. + In the FileSystem example, the init() method is used to create and add two resource instances:

+ public void init() throws Exception + { + super.init(); + add( createInstance( LVOL1_ID ) ); + add( createInstance( LVOL2_ID ) ); + } +

The createInstance() method:

Creates an instance of the resource.
Sets the resource's EndpointReference.
Calls init() on the resource.

+ + Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml Tue Oct 18 15:48:10 2005 @@ -10,7 +10,7 @@

The Developer Guide provides instructions for using many of the features that are included in Apache WSRF. If you are new to this project, you should start with the Getting Started and the Tutorial before reading this guide. They provide a good starting point for learning how to use Apache WSRF.

The Developer guide often refers to different parts of the Web Services Resource Framework (WSRF) specifications that are defined by +

The Developer Guide often refers to different parts of the Web Services Resource Framework (WSRF) specifications that are defined by the OASIS standards body. You should become familiar with these specifications and refer to them as needed.

The Developer Guide guide often refers to Apache Axis, Apache Tomcat, Apache Ant, and Apache XMLBeans. Instructions for these packages are included as required and are not meant to replace the formal documentation for these projects. Consult them as necessary.

@@ -20,9 +20,10 @@

WSRF Overview -

Apache WSRF is an implementation of the WSRF family of specifications that are defined by the OASIS standards body. Ultimately, the family - of specifications define a method of exposing resources using Web services. This is typically done for management purposes. The resource can - be anything from a device to application components or even current management components such as JMX MBeans.The specifications +

Apache WSRF is an implementation of the WSRF family of specifications that are defined by the OASIS standards body. + Ultimately, this family + of specifications defines a method of exposing resources using Web services. This is typically done for management purposes. The resource can + be anything from a device to an application component or even a current management component such as a JMX MBean. The specifications include:

WS Resource - Defines a WS-Resource and describes how one Web service can be used to represent multiple resource instances.

Resource Invocation Framework -

The resource invocation framework is the foundation upon which Apache WSRF is implemented. The framework includes a set of core interfaces, as well as +

The resource invocation framework is the foundation upon which Apache WSRF is implemented. + The framework includes a set of core interfaces, as well as runtime pieces. The framework is discussed in detail below.

@@ -88,7 +90,7 @@

A WSRF WSDL template for writing WSRF-compliant WSDLs

A Wsdl2Java tool for generating Java Classes from a WSDL

An integration with Apache XMLBeans for generating custom types defined in the WSDL

an integration with Apache Axis for automatically deploying WS Resources

An integration with Apache Axis for automatically deploying WS Resources

Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml Tue Oct 18 15:48:10 2005 @@ -1,114 +1,115 @@ - - - -

- Adding Service Metadata -

- -

- Introduction -

Web services may have various metadata associated with them (e.g. the WSDL for the service or a set of Topic Space documents). The - WS-MEXWS-Metadata Exchange specification (defined by Microsoft - and other industry contributors) defines operations that can be provided by services to allow clients to retrieve these metadata documents. -

- Define the Operations -

The metadata data operations are defined in your service's WSDL. If you used the INSTALL_DIR/template/_TEMPLATE_.wsdl file to create your WSDL, you simply - need to uncomment these operations in the portType and binding sections. -

- - ... - - - - - - - - - - - - - ... - - - - - - - - - - - - - - - - - - - -]]> -

- Modify the JNDI Configuration File -

The JNDI configuration file must be modified to include a metadata resource for your service as well as configurations that define where your metadata files are located.

To update the JNDI configuration file to include metadata information:

Using a text editor, open jndi-config.xml in the WEB-INF/classes directory.
Add the following JNDI resource block to the service, for which you would like to associate metadata: - - ]]> -
The org.apache.ws.util.jndi.tools.MetadataConfigImpl object containing the metadata is available via JNDI using a Context lookup of - wsrf/services/{service_name}/metadata - i.e. ctx.lookup("wsrf/services/sushi/metadata"); -
-
In the metadata resource block, add a metadataConfig element that contains metadata configurations. The configuration includes a dialect - attribute that defines the type of the data (xsd, wsdl, etc...) and an identifier attribute that uniquely identifies a particular document and is typically a targetNamespace. The - following examples demonstrate five different methods of configuring where your metadata files are located. The files should be "reachable" at the configured locations. - - - - org/apache/ws/resource/properties/SushiProperties.xsd - - - - - C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.wsdl - - - - - http://localhost:8080/wsrf/SushiProperties.xsd - - - - - file://C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.xsd - - - - - - http://localhost:8080/wsrf/services/sushi - - 1 - - - - -]]> -
Save and close jndi-config.xml.
Restart Tomcat if it is already started.

- - + + + +

+ Adding Service Metadata +

+ +

+ Introduction +

Web services may have various metadata associated with them (e.g. the WSDL for the service or a set of Topic Space documents). The + WS-Metadata Exchange (WS-MEx) specification (defined by Microsoft + and other industry contributors) defines operations that can be provided by services to allow clients to retrieve these metadata documents. +

+ Define the Operations +

The metadata operations are defined in your service's WSDL. If you used the INSTALL_DIR/template/_TEMPLATE_.wsdl file to create your WSDL, you simply + need to uncomment these operations in the portType and binding sections. +

+ + ... + + + + + + + + + + + + + ... + + + + + + + + + + + + + + + + + + + +]]> +

+ +

+ Modify the JNDI Configuration File +

The JNDI configuration file must be modified to include a metadata resource for your service as well as configurations that define where your metadata files are located.

To update the JNDI configuration file to include metadata information:

Using a text editor, open jndi-config.xml in the WEB-INF/classes directory.
Add the following JNDI resource block to the service, for which you would like to associate metadata: + + ]]> +
The org.apache.ws.util.jndi.tools.MetadataConfigImpl object containing the metadata is available via JNDI using a Context lookup of + wsrf/services/{service_name}/metadata - i.e. ctx.lookup("wsrf/services/sushi/metadata"); +
+
In the metadata resource block, add a metadataConfig element that contains metadata configurations. The configuration includes a dialect + attribute that defines the type of the data (xsd, wsdl, etc...) and an identifier attribute that uniquely identifies a particular document and is typically a targetNamespace. The + following examples demonstrate five different methods of configuring where your metadata files are located. The files should be "reachable" at the configured locations. + + + + org/apache/ws/resource/properties/SushiProperties.xsd + + + + + C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.wsdl + + + + + http://localhost:8080/wsrf/SushiProperties.xsd + + + + + file://C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.xsd + + + + + + http://localhost:8080/wsrf/services/sushi + + 1 + + + + +]]> +
Save and close jndi-config.xml.
Restart Tomcat if it is already started.

+ + Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml Tue Oct 18 15:48:10 2005 @@ -1,190 +1,190 @@ - - - -

- Writing a Service Class -

- -

- Introduction -

The service class is the representation of your WSDL file as a Web service. - The public methods in the service class correspond to the SOAP operations - exposed by your Web service. -

If you use the Wsdl2Java tool, the service class is automatically generated and typically does not need to be modified. However; this section discusses how - to write a service class if you choose to do so. Initially, you should model your service off of the included FileSystemService example to ensure that you write a - valid service.

- What classes will need to be written? -

The provided example FileSystem includes a FileSystemService class. - The FileSystemService extends AbstractFileSystemService, which contains - any code which should not need to be altered. The abstract class mainly - consists of the specification operations (i.e. getMultipleResourceProperties), - while the service class which extends this class contains the "custom" operations. - In the case of FileSystemService, the custom operations are mount and unmount. -

We recommend this structure for writing your service class, however you may write - the service however you like. Our description will describe the use of the abstract - class to separate the functionality. -

- The AbstractService class -

The abstract class is the superclass for your service and will contain most of the - specification-specific operations and utility operations. Our description of writing - the class will be based on the example.filesystem.AbstractFileSystemService class.

We will describe the class in sections:

- Class Declaration -
- WsrfService Interface -
- Class Variable -
- Operations -

- Class Declaration -

When declaring your abstract class, you must implement - org.apache.ws.resource.handler.WsrfService. This interface provides - methods for initialization, obtaining the ResourceContext and getting the - SoapMethodNameMap used for mapping incoming request QName's to method name - for a given object. It basically ensures that Apache WSRF can interact with your - service class. -

The AbstractFileSystemService class declaration is as follows:

- - abstract class AbstractFileSystemService implements WsrfService, - GetResourcePropertyPortType, - GetMultipleResourcePropertiesPortType, - SetResourcePropertiesPortType, - QueryResourcePropertiesPortType, - ImmediateResourceTerminationPortType, - ScheduledResourceTerminationPortType - -

You should notice that the class implements WsrfService (described above) and various *PortType - inerfaces. Each PortType interface is a Java representation of a specification's WSDL portType - declaration. By implementing the PortType interface corresponding to the specification-defined portTypes - you are interested in, you will ensure you get the correct method signature for the method call.

The packages: - org.apache.ws.resource.properties.porttype - and - - org.apache.ws.resource.lifetime.porttype - contain the interfaces for the - specifications. You should refer to these packages when selecting the operations you'd like - to support. -

- WsrfService Interface -

All Apache WSRF services must implement the WsrfService interface. The interface provides operation - "hooks" which will allow Apache WSRF to interact with your service. There are currenty three operations defined - by the interface:

- /** - * Returns the SoapMethodNameMap for the Service, to determine - * which method to invoke for an incoming request. - * - * @return SoapMethodNameMap - */ - public SoapMethodNameMap getMethodNameMap( ); - - /** - * Returns the ResourceContext for the given Service. - * - * @return ResourceContext - */ - public ResourceContext getResourceContext( ); - - /** - * Initialization method. - */ - public void init( ); -

The getMethodNameMap() returns a SoapMethodNameMap implementation which contains mappings of WSDL - operation QNames to Java method names. If you have custom operations you will need to create an instance of - ServiceSoapMethodName and add mappings for your operations. -

The getResourceContext() operation returns the ResourceContext associated with this service. This method may be - left abstract in this class and later implemented in the Service extension of your abstract class. -

The init() method is provided to give you an opportunity to initialize members for your Service - (e.g. ServiceSoapMethodName )

- Class Variables -

The class variables which should be defined are:

- - TARGET_NSURI - - The target namespace of your sevice's WSDL file.
- - TARGET_NSPREFIX - - The target prefix to be associated with your service's namespace.

In the AbstractFileSystem we have:

- public static final String TARGET_NSURI = "http://ws.apache.org/resource/example/filesystem"; -public static final String TARGET_NSPREFIX = "fs"; -

Notice the fields are public static final since they are constants that other classes may need to access.

- Operations -

The operations which are defined in the abstract class should be operations which typically should not need to be touched. The - specification operations are a prime example. Upon looking at the AbstractFileSystem class, we see the operations - defined for methods like: getMultipleResourceProperties(..). The body of these methods are similar in that they hand the - invocation off to a Provider class: -

- public GetMultipleResourcePropertiesResponseDocument getMultipleResourceProperties( GetMultipleResourcePropertiesDocument requestDoc ) -{ - return new GetMultipleResourcePropertiesProvider( getResourceContext( ) ).getMultipleResourceProperties( requestDoc ); -} -

Notice the GetMultipleResourcePropertiesProvider class being used. Providers are used to handle the specification - method calls. It provides a way to encapsulate the functionalty needed to handle a method call for a specific specification. Each - specification operation will have an equivalent *Provider class to handle a particular class.

The packages: - - org.apache.ws.resource.properties.porttype.impl - and - - org.apache.ws.resource.lifetime.porttype.impl - contain the Providers for the methods of the specifications. - You should refer to these packages when implementing the specification operations. -

- The Service class -

The service class is the extension of the abstract class we previously outlined. Because of the extension you will need to implement the - required method getResourceContext(). The ResourceContext should be passed in the constructor to the class and be - maintained as a class variable. -

The Service class should contain any custom operations as were defined in the WSDL for the service. The safest way to handle the - parameters and return type of the methods is to simply use XmlObject: -

- public XmlObject mount( XmlObject requestDoc ) - { - try - { - return XmlObject.Factory.parse( "]]>" ); - } - catch ( XmlException xe ) - { - throw new JAXRPCException( xe ); - } - } - -

XmlBeans will generate strongly-typed objects for the types defined in the schema section of - your WSDL document, and these types may be used, however if you are unsure which type will get - passed to your operation, you can be sure it will implement the XmlObject interface, since - all XmlBeans implement this interface.

- - + + + +

+ Writing a Service Class +

+ +

+ Introduction +

The service class is the representation of your WSDL file as a Web service. + The public methods in the service class correspond to the SOAP operations + exposed by your Web service. +

If you use the Wsdl2Java tool, the service class is automatically generated and typically does not need to be modified. However; this section discusses how + to write a service class if you choose to do so. Initially, you should model your service off of the included FileSystemService example to ensure that you write a + valid service.

+ What classes will need to be written? +

The provided example FileSystem includes a FileSystemService class. + The FileSystemService extends AbstractFileSystemService, which contains + any code which should not need to be altered. The abstract class mainly + consists of the specification operations (i.e. getMultipleResourceProperties), + while the service class which extends this class contains the "custom" operations. + In the case of FileSystemService, the custom operations are mount and unmount. +

We recommend this structure for writing your service class, however you may write + the service however you like. Our description will describe the use of the abstract + class to separate the functionality. +

+ The AbstractService class +

The abstract class is the superclass for your service and will contain most of the + specification-specific operations and utility operations. Our description of writing + the class will be based on the example.filesystem.AbstractFileSystemService class.

We will describe the class in sections:

+ Class Declaration +
+ WsrfService Interface +
+ Class Variable +
+ Operations +

+ Class Declaration +

When declaring your abstract class, you must implement + org.apache.ws.resource.handler.WsrfService. This interface provides + methods for initialization, obtaining the ResourceContext and getting the + SoapMethodNameMap used for mapping incoming request QName's to method name + for a given object. It basically ensures that Apache WSRF can interact with your + service class. +

The AbstractFileSystemService class declaration is as follows:

+ + abstract class AbstractFileSystemService implements WsrfService, + GetResourcePropertyPortType, + GetMultipleResourcePropertiesPortType, + SetResourcePropertiesPortType, + QueryResourcePropertiesPortType, + ImmediateResourceTerminationPortType, + ScheduledResourceTerminationPortType + +

You should notice that the class implements WsrfService (described above) and various *PortType + inerfaces. Each PortType interface is a Java representation of a specification's WSDL portType + declaration. By implementing the PortType interface corresponding to the specification-defined portTypes + you are interested in, you will ensure you get the correct method signature for the method call.

The packages: + org.apache.ws.resource.properties.porttype + and + + org.apache.ws.resource.lifetime.porttype + contain the interfaces for the + specifications. You should refer to these packages when selecting the operations you'd like + to support. +

+ WsrfService Interface +

All Apache WSRF services must implement the WsrfService interface. The interface provides operation + "hooks" which will allow Apache WSRF to interact with your service. There are currenty three operations defined + by the interface:

+ /** + * Returns the SoapMethodNameMap for the Service, to determine + * which method to invoke for an incoming request. + * + * @return SoapMethodNameMap + */ + public SoapMethodNameMap getMethodNameMap( ); + + /** + * Returns the ResourceContext for the given Service. + * + * @return ResourceContext + */ + public ResourceContext getResourceContext( ); + + /** + * Initialization method. + */ + public void init( ); +

The getMethodNameMap() returns a SoapMethodNameMap implementation which contains mappings of WSDL + operation QNames to Java method names. If you have custom operations you will need to create an instance of + ServiceSoapMethodName and add mappings for your operations. +

The getResourceContext() operation returns the ResourceContext associated with this service. This method may be + left abstract in this class and later implemented in the Service extension of your abstract class. +

The init() method is provided to give you an opportunity to initialize members for your Service + (e.g. ServiceSoapMethodName )

+ Class Variables +

The class variables which should be defined are:

+ + TARGET_NSURI + - The target namespace of your sevice's WSDL file.
+ + TARGET_NSPREFIX + - The target prefix to be associated with your service's namespace.

In the AbstractFileSystem we have:

+ public static final String TARGET_NSURI = "http://ws.apache.org/resource/example/filesystem"; +public static final String TARGET_NSPREFIX = "fs"; +

Notice the fields are public static final since they are constants that other classes may need to access.

+ Operations +

The operations which are defined in the abstract class should be operations which typically should not need to be touched. The + specification-defined operations are a prime example. Upon looking at the AbstractFileSystem class, we see the operations + defined for methods like: getMultipleResourceProperties(...). The body of these methods are similar in that they hand the + invocation off to a portType implementation class: +

+ public GetResourcePropertyResponseDocument getResourceProperty( GetResourcePropertyDocument requestDoc ) + { + return new GetResourcePropertyPortTypeImpl( getResourceContext( ) ).getResourceProperty( requestDoc ); + } +

Notice the GetMultipleResourcePropertiesPortTypeImpl class being used. A portType implementation class + is used to handle the operations defined in a particular specification-defined portType.

The packages: + + org.apache.ws.resource.properties.porttype.impl + and + + org.apache.ws.resource.lifetime.porttype.impl + contain the portType implementation classes for the portTypes defined by + the WS-ResourceProperties and WS-ResourceLifetime specifications. + You should refer to these packages when implementing the operations from these specifications. +

+ The Service class +

The service class is the extension of the abstract service class we previously outlined. + You will need to implement a constructor that takes a ResourceContext as a parameter. This + constructor should call the equivalent constructor in the superclass. +

The Service class should contain any custom operations that were defined in the most-derived portType for the service. The safest way to handle the + parameters and return type of the methods is to simply use XmlObject: +

+ public XmlObject mount( XmlObject requestDoc ) + { + try + { + return XmlObject.Factory.parse( "]]>" ); + } + catch ( XmlException xe ) + { + throw new JAXRPCException( xe ); + } + } + +

XmlBeans will generate strongly-typed objects for the types defined in the schema section of + your WSDL document, and these types may be used, however if you are unsure which type will get + passed to your operation, you can be sure it will implement the XmlObject interface, since + all XmlBeans implement this interface.

+ + Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml?rev=326288&r1=326287&r2=326288&view=diff ============================================================================== --- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml (original) +++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml Tue Oct 18 15:48:10 2005 @@ -114,8 +114,8 @@ Example

The following example generates files for a single WSDL and places the generated files in a subdirectory - of the current directory named /generated. To simplify the example, the classpath is referenced. You must set the ${wsrf.home} Ant property to - INSTALL_DIR (e.g. /opt/wsrf-1.0).

+ of the current directory named generated. To simplify the example, the classpath is referenced. You must set the ${wsrf.home} Ant property to

 
+			 INSTALL_DIR

(e.g. /opt/wsrf-1.1).