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 jr...@apache.org on 2005/07/12 19:05:00 UTC
svn commit: r215983 -
/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml
Author: jruzzi
Date: Tue Jul 12 10:04:59 2005
New Revision: 215983
URL: http://svn.apache.org/viewcvs?rev=215983&view=rev
Log:
completed overview
Modified:
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/index.xml
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=215983&r1=215982&r2=215983&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 Jul 12 10:04:59 2005
@@ -10,58 +10,87 @@
<p>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 <a href="site:overview">Getting Started</a> and the <a href="site:tut">Tutorial</a> before reading this guide. They provide a good starting point for
learning how to use Apache WSRF.</p>
- <p>The Developer guide often refers to different parts of the <a href="site:wsrf">Web Services Resource Framework (WSRF) specifications that are defined by
- the OASIS standards body</a>. You should become familiar with these specifications and refer to them as needed.</p>
- <p>The Developer Guide guide often refers to Apache Axis, Apache Tomcat, Apache Ant, and Apache XMLBeans. Instuctions for these pacakages are included
- as required and are not meant to replace the formal documentation for these projects. Consult them as neccassary.</p>
+ <p>The Developer guide often refers to different parts of the <a href="site:wsrf">Web Services Resource Framework (WSRF) specifications</a> that are defined by
+ the OASIS standards body. You should become familiar with these specifications and refer to them as needed.</p>
+ <p>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.</p>
<p>Lastly, Apache WSRF is consumed by the <a href="ext:pubscribe">Pubscribe</a> and <a href="ext:muse">Muse</a> projects. Many of the concepts that are
covered in this guide are also applicable to Pubscribe and Muse. While it is not required, it is a good idea to start with Apache WSRF before
moving on to these other projects.</p>
- </section>
- <section>
- <title>Conceptual Overview</title>
-
- <p>Apache WSRF can be divided into three parts:</p>
+ </section>
+ <section>
+ <title>WSRF Overview</title>
+ <p>Apache WSRF is an implementation of the <a href="site:wsrf">WSRF</a> 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
+ include:</p>
<ul>
- <li>a resource invocation framework</li>
- <li>APIs for WSRF resource properties, base faults, etc...</li>
- <li>implementations of the operations defined by the WS-ResourceProperties and WS-ResourceLifetime specifications</li>
+ <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
+ purpose.
+ <note>This 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>
</ul>
- <note>APIs and operation implementations are not currently provided for the WS-ServiceGroup specification.</note>
+ </section>
+ <section>
+ <title>Resource Invocation Framework</title>
+ <p> 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.
+ </p>
+ <section>
+ <title>Core Interfaces</title>
+ <p>The resource invocation framework revolves around several core interfaces:</p>
+ <ul>
+ <li>WsrfService - represents a WSRF service (i.e. a service that represents the external interface for a set of WS-Resource instances of a particular type)</li>
+ <li>Resource - represents a WS-Resource as defined by the WS-Resource specification.</li>
+ <li>ResourceHome - provides a way to instantiate and lookup Resource instances; there is one ResourceHome object per type of Resource</li>
+ <li>ResourceContext - provides request context information to the WSRF service</li>
+ </ul>
+ </section>
<section>
- <title>Resource Invocation Framework</title>
- <p>The resource invocation framework revolves around several core interfaces:</p>
+ <title>Runtime Behavior</title>
+ <p>At runtime, the entry point to the framework is the ResourceHandler. The ResourceHandler is implemented as a JAX-RPC 1.1 handler to allow it to run inside of
+ any JAX-RPC-based SOAP engine. Since it acts as a request dispatcher, it belongs either as the pivot point of the handler chain or as the last handler in the chain.
+ For each incoming SOAP request, the ResourceHandler performs the following steps:
+ </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>
+ <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>
+ <li>based on either the request body element or the wsa:Action header (this is configurable on a per-operation basis), maps the request to a particular
+ method of the service object, invoking that method with the request XmlObject as a parameter;</li>
+ <li>serializes the XmlObject returned by the method and adds it to the body of the response message.</li>
+ </ol>
+ <p>Schema validation of incoming requests is a powerful feature. When validation fails, a fault is returned to the client that contains a detailed description of
+ exactly what is wrong with the XML. Request validation is not only powerful, but it is also efficient, since it is performed via XMLBeans, which uses an in-memory
+ binary schema store. Nevertheless, if the utmost performance is required, request validation can be disabled.
+ </p>
+ <p>As described above, when the ResourceHandler creates a service instance, it passes it a ResourceContext object. From the context, methods in the service
+ an obtain the specific resource instance that was targeted by the current request; this is accomplished by simply calling the getResource method on the context.
+ Under the hood, the context uses the service name as a key to lookup the resource home object from JNDI. It then extracts a resource key Object from the header
+ portion of the SOAP request and uses this key to lookup a resource instance from the home. If there is no resource registered in the home with the specified key, a
+ ResourceUnknownException is thrown, which ultimately is propagated back to the client as a ResourceUnknownFault WSRF base fault.
+ </p>
+ </section>
+ </section>
+ <section>
+ <title>Design-Time</title>
+ <p>A set of tools and integrations are provided that facilitate developing WSRF-compliant Web services. They are provided to help developers focus on
+ defining their WS Resource without having to deal with low-level implementation details.</p>
+ <note>These tools and integrations are not required to create WSRF-compliant Web services, but are instead provided to save you time.</note>
+ <p>The tools and integrations include:</p>
<ul>
- <li>WsrfService - represents a WSRF service (i.e. a service that represents the external interface for a set of WS-Resource instances of a particular type)</li>
- <li>Resource - represents a WS-Resource as defined by the WS-Resource specification.</li>
- <li>ResourceHome - provides a way to instantiate and lookup Resource instances; there is one ResourceHome object per type of Resource</li>
- <li>ResourceContext - provides request context information to the WSRF service</li>
+ <li>A WSRF WSDL template for writing WSRF-compliant WSDLs</li>
+ <li>A Wsdl2Java tool for generating Java Classes from a WSDL</li>
+ <li>An integration with Apache XMLBeans for generating custom types defined in the WSDL</li>
+ <li>an integration with Apache Axis for automatically deploying WS Resources</li>
</ul>
- <p>At runtime, the entry point to the framework is the ResourceHandler. The ResourceHandler is implemented as a JAX-RPC 1.1 handler to allow it to run inside of
- any JAX-RPC-based SOAP engine. Since it acts as a request dispatcher, it belongs either as the pivot point of the handler chain or as the last handler in the chain.
- For each incoming SOAP request, the ResourceHandler performs the following steps:
- </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>
- <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>
- <li>based on either the request body element or the wsa:Action header (this is configurable on a per-operation basis), maps the request to a particular
- method of the service object, invoking that method with the request XmlObject as a parameter;</li>
- <li>serializes the XmlObject returned by the method and adds it to the body of the response message.</li>
- </ol>
- <p>Schema validation of incoming requests is a powerful feature. When validation fails, a fault is returned to the client that contains a detailed description of
- exactly what is wrong with the XML. Request validation is not only powerful, but it is also efficient, since it is performed via XMLBeans, which uses an in-memory
- binary schema store. Nevertheless, if the utmost performance is required, request validation can be disabled.
- </p>
- <p>As described above, when the ResourceHandler creates a service instance, it passes it a ResourceContext object. From the context, methods in the service
- an obtain the specific resource instance that was targeted by the current request; this is accomplished by simply calling the getResource method on the context.
- Under the hood, the context uses the service name as a key to lookup the resource home object from JNDI. It then extracts a resource key Object from the header
- portion of the SOAP request and uses this key to lookup a resource instance from the home. If there is no resource registered in the home with the specified key, a
- ResourceUnknownException is thrown, which ultimately is propagated back to the client as a ResourceUnknownFault WSRF base fault.
- </p>
- </section>
</section>
</body>
</document>