You are viewing a plain text version of this content. The canonical link for it is here.
Posted to wsrf-dev@ws.apache.org by sc...@apache.org on 2004/12/15 22:42:24 UTC
svn commit: r112025 - /incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml
Author: scamp
Date: Wed Dec 15 13:42:23 2004
New Revision: 112025
URL: http://svn.apache.org/viewcvs?view=rev&rev=112025
Log:
Updated the documentation for writing a service class
Modified:
incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml
Modified: incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml
Url: http://svn.apache.org/viewcvs/incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml?view=diff&rev=112025&p1=incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml&r1=112024&p2=incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml&r2=112025
==============================================================================
--- incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml (original)
+++ incubator/apollo/trunk/src/site/content/xdocs/tutorial/service.xml Wed Dec 15 13:42:23 2004
@@ -10,51 +10,55 @@
<p>
The service class is the representation of your WSDL file as a Web service. The public operations in the service class are the operations which will be invokable when a SOAP request is received for your service.
</p>
- <p>This section will discuss how to write a service class. Please note that the eventual goal will be to generate most of this code for you via code generation. Currently, however, you will need to implement these classes by hand.</p>
-<p>Initially, you should model your service off of the included FileSystem example. This will ensure you will write a working service.</p>
- <ul>
- <li><a href="#intro">What files will need to be written?</a></li>
- <li><a href="#abstract">The AbstractService class.</a></li>
- <li><a href="#service">The Service class.</a></li>
- </ul>
+ <p>This section will discuss how to write a service class. Please note that the eventual goal will be to generate most of this code for you via code generation. Currently, however, you will need to implement these classes by hand.</p>
+ <p>Initially, you should model your service off of the included FileSystem example. This will ensure you will write a working service.</p>
</section>
<section id="intro">
<title>What files will need to be written?</title>
<p>The provided example "FileSystem" includes a FileSystemService. The FileSystemService extends AbstractFileSystemService to abstract out the code which should not need to be altered. The abstract class mainly consists of the specification operations (i.e. getMultipleResourceProperties) and the service class which extends this class contains the user-specific operations. In the case of FileSystemService, these operations are "mount" and "unmount".</p>
- <p>
+ <p>
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 seperate the functionality.
</p>
-
- <section id="abstract">
- <title>The AbstractService class.</title>
- <p>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.</p>
- <p>We will describe the class in sections:</p>
- <ol>
- <li><a href="#class-declaration">Class Declaration</a></li>
- <li><a href="#wsrfservice">WsrfService Interface</a></li>
- <li><a href="#classvars">Class Variable</a></li>
- <li><a href="#ops">Operations</a></li>
- </ol>
-
- <section id="class-declaration">
- <title>Class Declaration</title>
- <p>When declaring your abstract class, you must implement <code>org.apache.ws.resource.handler.WsrfService</code>. This interface provides methods for initialization, obtaining the ResourceContext and getting the SoapMethodNameMap use for mapping incoming request QName's to method name for a given object. It basically ensures that Apollo can interact with your service class.</p>
- <p>The AbstractFileSystemService's class declaration is as follows:</p>
- <source><strong> abstract class AbstractFileSystemService
+ <section id="abstract">
+ <title>The AbstractService class.</title>
+ <p>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.</p>
+ <p>We will describe the class in sections:</p>
+ <ol>
+ <li>
+ <a href="#class-declaration">Class Declaration</a>
+ </li>
+ <li>
+ <a href="#wsrfservice">WsrfService Interface</a>
+ </li>
+ <li>
+ <a href="#classvars">Class Variable</a>
+ </li>
+ <li>
+ <a href="#ops">Operations</a>
+ </li>
+ </ol>
+ <section id="class-declaration">
+ <title>Class Declaration</title>
+ <p>When declaring your abstract class, you must implement <code>org.apache.ws.resource.handler.WsrfService</code>. This interface provides methods for initialization, obtaining the ResourceContext and getting the SoapMethodNameMap use for mapping incoming request QName's to method name for a given object. It basically ensures that Apollo can interact with your service class.</p>
+ <p>The AbstractFileSystemService's class declaration is as follows:</p>
+ <source>
+ <strong> abstract class AbstractFileSystemService
implements WsrfService,
GetResourcePropertyPortType,
GetMultipleResourcePropertiesPortType,
SetResourcePropertiesPortType,
QueryResourcePropertiesPortType,
ImmediateResourceTerminationPortType,
- ScheduledResourceTerminationPortType</strong></source>
- <p>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's/portTypes you are interested in, you will ensure you get the correct method signature for the method call.</p> <p>The packages: <strong>org.apache.ws.resource.properties.porttype</strong> and <strong>org.apache.ws.resource.lifetime.porttype</strong> contain the interfaces for the specifications. You should refer to these packages when selecting the operations you'd like to support.
- </p>
- </section>
- <section id="wsrfservice">
- <title>WsrfService Interface</title>
- <p>All services in Apollo need to implement the WsrfService interface. The interface provides operation "hooks" which will allow Apollo to interact with your service. There are currenty three operations defined by the interface:</p>
-<source> /**
+ ScheduledResourceTerminationPortType</strong>
+ </source>
+ <p>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's/portTypes you are interested in, you will ensure you get the correct method signature for the method call.</p>
+ <p>The packages: <strong>org.apache.ws.resource.properties.porttype</strong> and <strong>org.apache.ws.resource.lifetime.porttype</strong> contain the interfaces for the specifications. You should refer to these packages when selecting the operations you'd like to support.
+ </p>
+ </section>
+ <section id="wsrfservice">
+ <title>WsrfService Interface</title>
+ <p>All services in Apollo need to implement the WsrfService interface. The interface provides operation "hooks" which will allow Apollo to interact with your service. There are currenty three operations defined by the interface:</p>
+ <source> /**
* Returns the SoapMethodNameMap for the Service, to determine
* which method to invoke for an incoming request.
*
@@ -73,27 +77,53 @@
* Initialization method.
*/
public void init( );</source>
+ <p>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 you operations.</p>
+ <p>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.</p>
+ <p>The init() method is provided to give you an opportunity to initialize members for your Service (i.e. ServiceSoapMethodName )</p>
+ </section>
+ <section id="classvars">
+ <title>Class Variables</title>
+ <p>The class variables which should be defined are:</p>
+ <ol><li><strong>TARGET_NSURI</strong> - The target namespace of your sevice's WSDL file.</li>
+ <li><strong>TARGET_NSPREFIX</strong> - The target prefix to be associated with your service's namespace.</li>
+ </ol>
+ <p> In the AbstractFileSystem we have:</p>
+ <source>public static final String TARGET_NSURI = "http://ws.apache.org/resource/example/filesystem";
+public static final String TARGET_NSPREFIX = "fs";</source>
- <p>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 extend SoapMethodNameM</p>
- </section>
-
- <section id="classvars">
- <title>Class Variable</title>
- <p></p>
+ <p>Notice the fields are "public static final" since they should not change and are easily accessible.
+ </p>
+ </section>
+ <section id="ops">
+ <title>Operations</title>
+ <p>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:</p>
+<source>public GetMultipleResourcePropertiesResponseDocument getMultipleResourceProperties( GetMultipleResourcePropertiesDocument requestDoc )
+{
+ return new GetMultipleResourcePropertiesProvider( getResourceContext( ) ).getMultipleResourceProperties( requestDoc );
+}</source>
+<p>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.</p>
+<p>The packages: <strong>org.apache.ws.resource.properties.porttype.impl</strong> and <strong>org.apache.ws.resource.lifetime.porttype.impl</strong> contain the Providers for the methods of the specifications. You should refer to these packages when implementing the specification operations.
+ </p>
+ </section>
+
</section>
- <section id="ops">
- <title>Operations</title>
- <p></p>
- </section>
-
- </section>
- <section id="service">
+ <section id="service">
<title>The Service class.</title>
- <p></p>
- </section>
+ <p>The service class is the extension of the abstract class we previously outlined. Aside from the required method getResourceContext(), this 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:</p>
+<source> public XmlObject mount( XmlObject requestDoc )
+ {
+ try
+ {
+ return XmlObject.Factory.parse( "<![CDATA[<MountResponse />]]>" );
+ }
+ catch ( XmlException xe )
+ {
+ throw new JAXRPCException( xe );
+ }
+ }
+</source>
+<p>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 be XmlObject since it is the base class for all objects in XmlBeans.</p>
+ </section>
</section>
-
-
-
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: apollo-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: apollo-dev-help@ws.apache.org