You are viewing a plain text version of this content. The canonical link for it is here.
Posted to wsrf-commits@ws.apache.org by ip...@apache.org on 2005/07/29 01:24:20 UTC
svn commit: r226287 - in
/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide: callback.xml
home.xml index.xml resource.xml service.xml wsdl_tool.xml wsrf_wsdl.xml
Author: ips
Date: Thu Jul 28 16:24:16 2005
New Revision: 226287
URL: http://svn.apache.org/viewcvs?rev=226287&view=rev
Log:
minor edits
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/resource.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/service.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsdl_tool.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.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=226287&r1=226286&r2=226287&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 Thu Jul 28 16:24:16 2005
@@ -90,14 +90,14 @@
void insertProperty( Object[] prop );
void updateProperty( Object[] prop );</source>
<p>The operations will follow the same semantics as are defined in the specification and will be restricted to
- the bounds of you schema. If you define an element with a <code>maxOccurs="1"</code>, and attempt to add (insertProperty)
- another item to it, Apache WSRF will generate a fault.
+ the bounds defined by the resource properties document schema. If you define an element with a <code>maxOccurs="1"</code>,
+ and attempt to add (insertProperty) another item to it, Apache WSRF will generate a fault.
</p>
<p>
<code>CommentCallback</code> illustrates how these methods <em>may</em> be implemented:</p>
<source> public void deleteProperty( QName propQName )
{
- return; // no need to implement - Apache WSRFwill never call delete for a property whose minOccurs != 0
+ return; // no need to implement - Apache WSRF will never call delete for a property whose minOccurs != 0
}
public void insertProperty( Object[] propElems )
@@ -107,14 +107,16 @@
m_fileSystem.setComment( xString.getStringValue() );
}
- public void updateProperty( Object[] prop )
+ public void updateProperty( Object[] propElems )
{
insertProperty( prop );
}
</source>
<p>Notice that the <code>deleteProperty</code> method does nothing since the implementor knew that the method
would never be called since the schema forbids it. The <code>updateProperty</code> simply hands-off to the
- <code>insertProperty</code> since the implementor knew that an update on the backend is the same as an insert. The <code>insertProperty </code> method is the workhorse method and takes the <code>Object[]</code>, obtains the value from it and sets it on the backend.</p>
+ <code>insertProperty</code> since the implementor knew that an update on the backend is the same as an insert.
+ The <code>insertProperty</code> method is the workhorse method; it takes an array of property elements and
+ updates the corresponding backend property.</p>
</section>
<section id="register">
<title>Registering a Callback</title>
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=226287&r1=226286&r2=226287&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 Thu Jul 28 16:24:16 2005
@@ -11,10 +11,11 @@
<p>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.
</p>
- <note>If your service is a singleton and only requires a single resource instance, see the <a href="site:single">Creating a Singleton Service</a>section.</note>
- <p>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
+ <note>If your service is a singleton and only requires a single resource instance, see the <a href="site:single">Creating a Singleton Service</a> section.</note>
+ <p>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 <code>FilesystemHome</code> example
- to ensure that you write a valid home class for your resource.</p>
+ to ensure that you write a valid home class for your resource.
+ </p>
</section>
<section id="class-declaration">
<title>Class Declaration</title>
@@ -31,15 +32,16 @@
<title>Operations</title>
<p>If you extend <code>AbstractResourceHome</code>, the only required operation you will need to implement is:</p>
<source>public void init()</source>
- <p>The <code>init()</code> operation can be used to initialize any instances at startup. In the FileSystem example, the <code>init()</code> method is used:</p>
+ <p>The <code>init()</code> operation can be used to initialize any instances at startup.
+ In the FileSystem example, the <code>init()</code> method is used to create and add two resource instances:</p>
<source>public void init() throws Exception
{
- super.init();
+ super.init();
add( createInstance( LVOL1_ID ) );
- add( createInstance( LVOL2_ID ) );
+ add( createInstance( LVOL2_ID ) );
}</source>
<note>Many of the operations in the <code>AbstractResourceHome</code> may be overridden in your Home
- class, if you have a need to extend its functionality.</note>
+ class, if you have a need to modfify or extend the base class' functionality.</note>
</section>
</body>
</document>
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=226287&r1=226286&r2=226287&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 Thu Jul 28 16:24:16 2005
@@ -25,15 +25,14 @@
be anything from a device to application components or even current management components such as JMX MBeans.The specifications
include:</p>
<ul>
- <li>WS Resources - Defines a WS-Resource, which describes the relationship between a Web service and a resource in the WS-Resource.
- Framework.</li>
- <li>WS-ResourceProperties (WSRF-RP) - Defines how to define and interact with the properties of a WS Resource.</li>
- <li>WS-ResourceLifetime (WSRF-RL) - Defines a way in which the lifetime of a WS-Resource can be monitored and how the WS Resource can be destroyed. </li>
- <li>WS-ServiceGroup (WSRF-SG) - Defines a way in which Web services and WS-Resources can be aggregated or grouped together for a domain specific
+ <li>WS Resource - Defines a WS-Resource and describes how one Web service can be used to represent multiple resource instances.</li>
+ <li>WS-ResourceProperties (WSRF-RP) - Defines how to define and interact with stateful properties of a WS-Resource.</li>
+ <li>WS-ResourceLifetime (WSRF-RL) - Defines a way in which the lifetime of a WS-Resource can be monitored and how the WS-Resource can be destroyed. </li>
+ <li>WS-ServiceGroup (WSRF-SG) - Defines how WS-Resources can be aggregated or grouped together for a domain specific
purpose.
- <note>This specification is currently not implemented in Apache WSRF.</note>
+ <note>The WS-ServiceGroup specification is currently not implemented in Apache WSRF.</note>
</li>
- <li>WS-BaseFaults (WSRF-BF) - Defines how to specify Web services fault messages in a common way.</li>
+ <li>WS-BaseFaults (WSRF-BF) - Defines a standard format for SOAP faults thrown by WSRF services.</li>
</ul>
</section>
<section>
@@ -59,7 +58,7 @@
</p>
<ol>
<li>deserializes the contents of the request message body to an XMLBeans XmlObject and then validates this XmlObject according to its schema type as it was
- defined in the serviceâs WSDL;</li>
+ defined in the service's WSDL;</li>
<li>creates a ResourceContext and populates it with vital information associated with the request such as the service name, the service URL, and the
JAX-RPC SOAPMessageContext;</li>
<li>based on the name of the service to which the request was sent, instantiates the appropriate type of service object, passing it the ResourceContext;</li>
Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/resource.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/resource.xml?rev=226287&r1=226286&r2=226287&view=diff
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/resource.xml (original)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/resource.xml Thu Jul 28 16:24:16 2005
@@ -21,7 +21,8 @@
will use the resource <code>id</code> to look up the corresponding resource instance to
service the request.
</p>
- <p>If you use the Wsdl2Java tool, the resource class is automatically generated, but will need to modified to include any custom operations. This section discuss
+ <p>If you use the Wsdl2Java tool, the resource class is automatically generated, but code will need to be added
+ to initialize the resource's <code>ResourcePropertySet</code>. This section discuss
how to write a resource class. Initially, you should model your resource off of the included <code>FileSystemResource</code> example to
ensure that you write a valid resource class.</p>
</section>
@@ -58,10 +59,9 @@
<section id="methods">
<title>Methods</title>
<p>The methods are defined by the interfaces you implement and are mainly setters and
- getters for the <code>ResourcePropertySet</code> and the resource <code>id</code>. There are also operations
- which allow you to initialize your resource or destroy your resource (<code>init(..) </code>and
- <code>destroy()</code>). The operations allow you to do setup, initialize your resource properties,
- add callback objects, and do cleanup in your resource class.
+ getters for the <code>ResourcePropertySet</code> and the resource <code>id</code>. There are also
+ <code>init()</code>and <code>destroy()</code> operations
+ which allow you to initialize or clean up your resource.
</p>
</section>
</body>
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=226287&r1=226286&r2=226287&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 Thu Jul 28 16:24:16 2005
@@ -13,7 +13,7 @@
exposed by your Web service.
</p>
<p>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 chose to do so. Initially, you should model your service off of the included FileSystemService example to ensures that you write a
+ 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.</p>
</section>
<section id="classes">
@@ -23,7 +23,7 @@
any code which should not need to be altered. The abstract class mainly
consists of the specification operations (i.e. <code>getMultipleResourceProperties</code>),
while the service class which extends this class contains the "custom" operations.
- In the case of <code>FileSystemService</code>, these operations are <code>mount</code> and <code>unmount</code>.
+ In the case of <code>FileSystemService</code>, the custom operations are <code>mount</code> and <code>unmount</code>.
</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
@@ -70,7 +70,7 @@
</source>
<p>You should notice that the class implements <code>WsrfService</code> (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
+ 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. </p>
<p>The packages:<strong>
<code>org.apache.ws.resource.properties.porttype</code>
@@ -132,7 +132,7 @@
<p> In the <code>AbstractFileSystem</code> 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>Notice the fields are <code>public static final</code> since they should not change and are easily accessible.</p>
+ <p>Notice the fields are <code>public static final</code> since they are constants that other classes may need to access.</p>
</section>
<section id="ops">
<title>Operations</title>
@@ -163,7 +163,7 @@
<title>The Service class</title>
<p>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 <code>getResourceContext()</code>. The ResourceContext should be passed in the constructor to the class and be
- maintained as a class variable. The ResourceContext will be passed, upon construction, to the Service via the Home class.
+ maintained as a class variable.
</p>
<p>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 <code>XmlObject</code>:
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=226287&r1=226286&r2=226287&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 Thu Jul 28 16:24:16 2005
@@ -8,16 +8,16 @@
<body>
<section>
<title>Introduction</title>
- <p>The Wsdl2Java tool is used to generate a set of artificats for a WS Resource. The artifiacts include:</p>
+ <p>The Wsdl2Java tool is used to generate a set of artificats for a WS Resource. The artifacts include:</p>
<ul>
<li>A set of Java classes based on the WSDL definition. This includes a service, resource, and
home class. Some of the Java code will need to be manually edited after the files are generated.</li>
<li>Interfaces for custom operations.</li>
- <li>Java bindings for all Types that are defined in the WSDL. The interfaces and classes are
+ <li>Java bindings for all XML schema types that are defined in the WSDL. The interfaces and classes are
created using the <a href="ext:xmlbeans.apache.org">XMLBeans</a> schema compiler</li>
<li>An Axis Web Service Deployment Descriptor (WSDD) for your service (<em>service</em>_deploy.wsdd). This file is used to deploy your service to
Axis.</li>
- <li>A JNDI Resource configuration file for your service (<em>service</em>_jndi-config.xml). The file is used to setup the in-memory JNDI context for
+ <li>A JNDI resource configuration file for your service (<em>service</em>_jndi-config.xml). The file is used to setup the in-memory JNDI context for
your generated service, resource, and home classes.</li>
</ul>
<p>The tool saves you a great deal of time, since these files do not have to be created from scratch. You simply pass the tool a WSRF WSDL and the files
@@ -113,9 +113,9 @@
<p>
<strong>Example</strong>
</p>
- <p>The following example generates files for a single WSDL and places the generated files in a directory
- named <code>/generated</code>. To simplify the example, the classpath is referenced. You must set the <code>${wsrf.home}</code> Ant property to <code>
- INSTALL_DIR</code> (e.g. /opt/wsrf-1.0beta).</p>
+ <p>The following example generates files for a single WSDL and places the generated files in a subdirectory
+ of the current directory named <code>/generated</code>. To simplify the example, the classpath is referenced. You must set the <code>${wsrf.home}</code> Ant property to <code>
+ INSTALL_DIR</code> (e.g. /opt/wsrf-1.0).</p>
<source><![CDATA[
<property name="wsrf.webapp.dir" location="${wsrf.home}/webapps/wsrf" />
Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml?rev=226287&r1=226286&r2=226287&view=diff
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml (original)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml Thu Jul 28 16:24:16 2005
@@ -27,8 +27,8 @@
and custom resource-specific operations. The specification-defined portTypes that are discussed below include:
</p>
<ul>
- <li>WS-ResourceProperties (WSRF-RP) PortTypes</li>
- <li>WS-ResourceLifetime (WSRF-RL) PortTypes</li>
+ <li>WS-ResourceProperties (WSRF-RP) portTypes</li>
+ <li>WS-ResourceLifetime (WSRF-RL) portTypes</li>
</ul>
<p>If you've copied the WSDL template file as described above, your WSDL file
already contains a WSRF-compliant portType. You simply have to rename the portType (<code>MyPortType</code>) and the binding (MySoapHttpBinding) and
@@ -63,8 +63,8 @@
<td/>
</tr>
</table>
- <note>The GetResourceProperty portType is REQUIRED. The WS-Resource specification states that
- all WS-Resources MUST implement this portType.</note>
+ <note>If your portType has an associated resource properties document, then the WSRF-RP specification
+ REQUIRES that you implement the GetResourceProperty portType (i,e, the GetResourceProperty operation).</note>
</section>
<section>
<title>WS-ResourceLifetime (WSRF-RL) PortTypes</title>
@@ -89,15 +89,16 @@
</table>
<note>In addition to operations, the <code>ScheduledResourceTermination</code> portType also includes two properties. If a
WS-Resource implements this portType, it must also expose these properties.</note>
- <p>The PortType element must have a
+
+ <p>If your WS-Resource exposes any resource properties, the PortType element must have a
<code>{http://docs.oasis-open.org/wsrf/2004/11/wsrf-WS-ResourceProperties-1.2-draft-05.xsd}ResourceProperties</code>
- attribute whose value is the <code>QName</code> of the resource properties document element defined
+ attribute whose value is the <code>QName</code> of a resource properties document element defined
in the types/schema section of the WSDL file.
</p>
</section>
<section>
<title>Metadata Operations</title>
- <p>The template contains two operations that are not defined by the WSRF specification that can be used in your service to retrieve metadata
+ <p>The template contains two operations that are not defined by the WSRF specifications that can be used in your service to retrieve metadata
about your services. The operations and messages are defined in the
<a href="http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-metadataexchange.pdf">WS-Metadata Exchange</a> specification defined by Microsoft and other industry
contributors. For instructions on providing metadata about your service, see the <a href="site:metadata">Adding Service Metadata</a> section.</p>
@@ -127,7 +128,7 @@
implements the WSRF-RL ScheduledResourceTermination portType, simply
uncomment the xsd element references, which correspond to the two ScheduledResourceTermination
properties. If would like your WS-Resource to allow resource properties with arbitrary names
- (not generally recommended), simply uncomment the xsd <code>any</code> element.
+ (not generally recommended), uncomment the xsd <code>any</code> element.
</p>
</section>
</body>