You are viewing a plain text version of this content. The canonical link for it is here.
Posted to muse-commits@ws.apache.org by sc...@apache.org on 2006/06/02 19:30:35 UTC
svn commit: r411217 [4/5] - in
/webservices/muse/branches/1.0/src/site/content/xdocs: ./ muse/
muse/dev_guide/ muse/tutorial/ muse/tutorial/images/ pubscribe/
pubscribe/dev_guide/ pubscribe/tutorial/ pubscribe/tutorial/images/ wsrf/
wsrf/dev_guide/ wsr...
Modified: webservices/muse/branches/1.0/src/site/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/site.xml?rev=411217&r1=411216&r2=411217&view=diff
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/site.xml (original)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/site.xml Fri Jun 2 10:30:32 2006
@@ -13,7 +13,7 @@
See http://forrest.apache.org/docs/linking.html for more info.
-->
<site label="Muse" href="" xmlns="http://apache.org/forrest/linkmap/1.0">
- <project label="Project Info" tab="home">
+ <project label="Project Info" href="" tab="home">
<index label="Overview" href="index.html"/>
<vcs label="Version Control" href="version_control.html"/>
<issues label="Issue Tracking" href="issue_tracking.html"/>
@@ -24,14 +24,22 @@
<download label="Downloads" tab="home">
<releases label="Releases" href="release.html"/>
</download>
- <!-- **************** Documentation **************** -->
- <install label="Getting Started" tab="doc">
+
+ <projects label="Related Projects" tab="home">
+ <axis label="Axis" href="ext:axis"/>
+ <addressing label="Addressing" href="ext:addressing"/>
+ <xmlbeans label="XMLBeans" href="ext:xmlbeans.apache.org"/>
+ <maven label="Maven" href="ext:maven.apache.org"/>
+ </projects>
+ <!-- **************** Documentation **************** -->
+
+ <m_install label="Getting Started" href="muse/" tab="mdoc">
<overview label="Introduction" href="getting_started.html"/>
<installation href="getting_started.html#install"/>
<get label="Installation" href="getting_started.html#install"/>
<quick label="Quick Demo" href="getting_started.html#qd"/>
- </install>
- <tutorial label="Tutorial" href="tutorial/" tab="doc">
+ </m_install>
+ <m_tutorial label="Tutorial" href="muse/tutorial/" tab="mdoc">
<tut label="Overview" href="index.html"/>
<setup label="Create Workspace" href="setup.html"/>
<wsdl label="Create WSDLs" href="wsdl.html"/>
@@ -41,8 +49,8 @@
<modservice label="Modify Service Class" href="mod_service.html"/>
<webapp label="Deploy Services" href="webapp.html"/>
<test label="Test" href="test.html"/>
- </tutorial>
- <developer label="Developer Guide" href="dev_guide/" tab="doc">
+ </m_tutorial>
+ <m_developer label="Developer Guide" href="muse/dev_guide/" tab="mdoc">
<dev label="Overview" href="index.html"/>
<compose label="MuWS WSDL" href="wsdl.html"/>
<tool label="Using Wsdl2Java" href="wsdl_tool.html"/>
@@ -53,32 +61,80 @@
<deploy label="Deploying" href="deploy.html"/>
<client label="Using the SOAP Client" href="client.html"/>
<log label="Logging" href="debug.html"/>
- </developer>
- <projects label="Related Projects">
- <wsrf label="Apache WSRF" href="ext:wsrf/"/>
- <pubscribe label="Apache Pubscribe" href="ext:pubscribe/"/>
- <axis label="Axis" href="ext:axis"/>
- <addressing label="Addressing" href="ext:addressing"/>
- <xmlbeans label="XMLBeans" href="ext:xmlbeans.apache.org"/>
- <maven label="Maven" href="ext:maven.apache.org"/>
- </projects>
+ </m_developer>
+
+
+ <p_install label="Getting Started" href="pubscribe/" tab="pdoc">
+ <overview label="Introduction" href="getting_started.html"/>
+ <installation href="getting_started.html#install"/>
+ <get label="Installation" href="getting_started.html#install"/>
+ <quick label="Quick Demo" href="getting_started.html#qd"/>
+ </p_install>
+ <p_tutorial label="Tutorial" href="pubscribe/tutorial/" tab="pdoc">
+ <tut label="Overview" href="index.html"/>
+ <setup label="Create Workspace" href="setup.html"/>
+ <wsdl label="Create WSDL" href="wsdl.html"/>
+ <wsdl2java label="Run wsdl2Java Tool" href="wsdl2java.html"/>
+ <modhome label="Modify Home Class" href="mod_home.html"/>
+ <modresource label="Modify Resource Class" href="mod_resource.html"/>
+ <webapp label="Deploy Service" href="webapp.html"/>
+ <test label="Test" href="test.html"/>
+ </p_tutorial>
+ <p_developer label="Developer Guide" href="pubscribe/dev_guide/" tab="pdoc">
+ <dev label="Overview" href="index.html"/>
+ <p_compose label="WSRF/WSN WSDL" href="wsdl.html"/>
+ <tool label="Using Wsdl2Java" href="wsdl_tool.html"/>
+ <home label="Home Class" href="home.html"/>
+ <producer label="Notification Producer" href="producer.html"/>
+ <consumer label="Notification Consumer" href="consumer.html"/>
+ <subscript label="Subscription Manager" href="subscription.html"/>
+ <deploy label="Deploying" href="deploy.html"/>
+ <client label="Using the SOAP Client" href="client.html"/>
+ <log label="Logging" href="debug.html"/>
+ </p_developer>
+
+ <w_install label="Getting Started" href="wsrf/" tab="wdoc">
+ <overview label="Introduction" href="getting_started.html"/>
+ <installation href="getting_started.html#install"/>
+ <get label="Installation" href="getting_started.html#install"/>
+ <quick label="Quick Demo" href="getting_started.html#qd"/>
+ </w_install>
+ <w_tutorial label="Tutorial" href="wsrf/tutorial/" tab="wdoc">
+ <tut label="Overview" href="index.html"/>
+ <setup label="Create Workspace" href="setup.html"/>
+ <wsdl label="Create WSDL" href="wsdl.html"/>
+ <wsdl2java label="Run wsdl2Java Tool" href="wsdl2java.html"/>
+ <modhome label="Modify Home Class" href="mod_home.html"/>
+ <modresource label="Modify Resource Class" href="mod_resource.html"/>
+ <webapp label="Deploy Service" href="webapp.html"/>
+ <test label="Test" href="test.html"/>
+ </w_tutorial>
+ <w_developer label="Developer Guide" href="wsrf/dev_guide/" tab="wdoc">
+ <dev label="Overview" href="index.html"/>
+ <compose label="Composing a WSRF WSDL" href="wsrf_wsdl.html"/>
+ <tool label="Using Wsdl2Java" href="wsdl_tool.html"/>
+ <service label="Service Class" href="service.html"/>
+ <resource label="Resource Class" href="resource.html"/>
+ <home label="Home Class" href="home.html"/>
+ <callback label="Callback Objects" href="callback.html"/>
+ <metadata label="Metadata Operations" href="metadata.html"/>
+ <single label="Singleton Service" href="singleton.html"/>
+ <deploy label="Deploying" href="deploy.html"/>
+ <client label="Using the SOAP Client" href="client.html"/>
+ <validate label="Schema Validation" href="validate.html"/>
+ <log label="Logging" href="debug.html"/>
+ </w_developer>
+
<external-refs>
+
+ <wsrf href="wsrf/"/>
+
<xml.apache.org href="http://xml.apache.org/">
<forrest href="forrest/"/>
</xml.apache.org>
<xmlbeans.apache.org href="http://xmlbeans.apache.org/"/>
<maven.apache.org href="http://maven.apache.org/"/>
<ws.apache.org href="http://ws.apache.org/">
- <wsrf href="wsrf/"/>
- <wsrfwsdl href="wsrf/dev_guide/wsrf_wsdl.html"/>
- <spec href="wsrf/wsrf.html"/>
- <metadata href="wsrf/dev_guide/metadata.html"/>
- <single href="wsrf/dev_guide/singleton.html"/>
- <resource href="wsrf/dev_guide/resource.html"/>
- <pubscribe href="pubscribe/"/>
- <pubwsdl href="pubscribe/dev_guide/wsdl.html"/>
- <producer href="pubscribe/dev_guide/producer.html"/>
- <wsn href="pubscribe/wsn.html"/>
<mirrors href="mirrors.cgi"/>
<axis href="axis/"/>
<wsfx href="ws-fx/">
Modified: webservices/muse/branches/1.0/src/site/content/xdocs/tabs.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/tabs.xml?rev=411217&r1=411216&r2=411217&view=diff
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/tabs.xml (original)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/tabs.xml Fri Jun 2 10:30:32 2006
@@ -6,7 +6,9 @@
@href is not modified unless it is root-relative and obviously specifies a
directory (ends in '/'), in which case /index.html will be added
-->
- <tab id="home" label="Project Info" dir=""/>
- <tab id="doc" label="Documentation" dir="" indexfile="getting_started.html"/>
+ <tab id="home" label="Project Info" dir="" indexfile="index.html"/>
+ <tab id="mdoc" label="Muse Docs" dir="" indexfile="muse/getting_started.html"/>
+ <tab id="wdoc" label="WSRF Docs" dir="" indexfile="wsrf/getting_started.html"/>
+ <tab id="pdoc" label="Pubscribe Docs" dir="" indexfile="pubscribe/getting_started.html"/>
<tab label="API Docs" dir="apidocs/"/>
</tabs>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/callback.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/callback.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/callback.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/callback.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,128 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Writing Callback Objects</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>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 <code>init</code> method. An example of this can be seen in
+ <code> FileSystemResource</code>.
+ </p>
+ <p>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:
+ </p>
+ <ul>
+ <li>
+ <code>org.apache.ws.resource.properties.ResourcePropertyCallback</code> - 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.
+ </li>
+ <li>
+ <code>org.apache.ws.resource.properties.SetResourcePropertyCallback</code> - Implement this interface if the resource property is
+ modifiable, thus methods like<code> insert</code>, <code>update</code> and <code>delete</code>
+ <em>may</em> be appropriate. This interface extends <code>ResourcePropertyCallback</code>.
+ </li>
+ </ul>
+ </section>
+ <section id="refresh">
+ <title>Implementing a ResourcePropertyCallback</title>
+ <p>
+ <code>ResourcePropertyCallback</code> is a way for you to synchronize the front-end resource properties with the backend. The
+ interface defines one method:
+ </p>
+ <source>ResourceProperty refreshProperty( ResourceProperty prop );</source>
+ <p>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)
+ </p>
+ <p>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
+ (<code>string</code>,<code> int</code> etc.), XmlBeans provides objects specific to those types. In
+ <code>BackupFrequencyCallback</code> we see that <code>BackupFrequency</code> was an <code>xsd:int</code> and so the XmlBean
+ type is <code>XmlInt</code>:
+ </p>
+ <source>public ResourceProperty refreshProperty(ResourceProperty prop)
+ {
+ XmlInt xInt = (XmlInt) prop.get( 0 );
+ xInt.setIntValue( m_fileSystem.getBackupFrequency() );
+ return prop;
+ }</source>
+ <p>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 <code>OptionsCallback</code>:
+ </p>
+ <source> 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 <![CDATA[<]]> options.size( ); i++ )
+ {
+ o.addOption( options.get( i ).toString( ) );
+ }
+ }
+
+ return prop;
+ }</source>
+ <p>In both cases the objects (<code>XmlInt</code> and<code> Options</code>) all extend <code>XmlObject</code> as a common class,
+ however it is useful to utilize the defined class' operations directly.
+ </p>
+ <p>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.
+ </p>
+ <p>The <code>refreshProperty</code> method is called by Apache WSRF before servicing <code>GetResourceProperty</code>, <code>GetMultipleResourceProperties</code> and <code>QueryResourceProperties</code> requests.
+ </p>
+ </section>
+ <section id="setresource">
+ <title>Implementing the SetResourcePropertyCallback</title>
+ <p>
+ <code>SetResourcePropertyCallback</code> is a way for the backend to be changed via requests to the front-end resource properties.
+ The <code>SetResourcePropertyCallback</code> interface defines three methods:
+ </p>
+ <source>void deleteProperty( QName propQName );
+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 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 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 );
+ }
+ </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; it takes an array of property elements and
+ updates the corresponding backend property.</p>
+ </section>
+ <section id="register">
+ <title>Registering a Callback</title>
+ <p>Once you've written your callback objects you will need to register them with the resource properties.
+ This is done in the <code>init</code> method of your Resource implementation class. See the FileSystemResource
+ for an example.</p>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/client.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/client.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/client.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/client.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,38 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>SOAP Client</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>Apache WSRF includes a lightweight SOAP client that can be used to test your services. The client is invoked using an Ant script, which is located in
+ <code>INSTALL_DIR/template/soapclient.xml</code>. Request and response messages are viewed in the Ant output. This section explains how to use the client and
+ how to build request SOAP messages for the client.</p>
+ </section>
+ <section>
+ <title>SOAP Files</title>
+ <p>The client reads a <code>.soap</code> file which contains the SOAP envelope to be sent. Examples of SOAP files are located in
+ <code>INSTALL_DIR/examples/filesystem/requests/</code>. Each file is named appropriately based on the operation it contains. Use these files as models when
+ creating your own .soap files. Make sure you modify the WS-Addressing header for the resource id to match the entry that is in the JNDI
+ configuration file and the resource id for the instance you would like to invoke. The id is used by the invocation framework to lookup a particular resource instance.</p>
+ </section>
+ <section>
+ <title>Running the Client</title>
+ <p>To invoke the script:</p>
+ <ol>
+ <li>Make sure your WS Resource is deployed.</li>
+ <li>open a command prompt and change directories to <code>INSTALL_DIR/template/soapclient.xml</code>.</li>
+ <li>Run:
+ <source>ant -f soapclient.xml sendRequest -Durl=http://localhost:8080/wsrf/services/<em>your_service</em> -Dxml=./requests/QueryResourceProperties_allProps.soap</source>
+ <p>Where <em>your_service</em> represents your WS Resource endpoint name, and the script name should be the name (including the path) of your .soap file.
+ </p>
+ </li>
+ </ol>
+ <note>You can add an entry to <code>build.properties</code> for the <code>url</code> property, which alleviates the need
+ to specify it on the command line.</note>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/debug.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/debug.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/debug.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/debug.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,36 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Logging</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>Apache WSRF uses the Apache Commons Logging Framework with Log4j as the underlying logging system. You can configure Log4j using the log4j.properties
+ file. This includes changing log levels or where the output is emitted (e.g. stdout, log file, etc...). The properties file is located in the Apache WSRF Web application in
+ the WEB-INF/classes directory.
+ </p>
+ </section>
+ <section>
+ <title>Changing Log Levels</title>
+ <p>Log4j uses the following log levels: DEBUG, INFO, WARN, ERROR, and FATAL. By default, Apache WSRF is configured at the INFO level, which means messages logged
+ at INFO or higher level (i.e. INFO, WARN, ERROR, and FATAL) are included in the output. To see more
+ detailed log messages, you must change the log level. The following example assumes Tomcat.
+ </p>
+ <p>To change the logging level:</p>
+ <ol>
+ <li>Using a text editor, open the log4j.properties file located in the WEB-INF/classes directory of the deployed Apache WSRF Web application.</li>
+ <li>Change the log level associated with all classes below the <code>log4j.category.org.apache.ws</code> package. For example:<source>
+log4j.category.org.apache.ws=DEBUG</source>
+ </li>
+ <li>Save the log4j.properties file.</li>
+ <li>Restart Tomcat.
+ <note>Log messages are displayed in Tomcat's standard output. If you are not using Tomcat, you may need to configure your Web container to include the output
+ in its standard output.</note>
+ </li>
+ </ol>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/deploy.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/deploy.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/deploy.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/deploy.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,140 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Deploy the service to the Apache WSRF Web Application</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>The quickest way to deploy your WS-Resource is to use the generated build script. The script compiles and delploys your WS-Resource
+ to the Apache WSRF Web application, which is an Apache-Axis Web application. This section describes how to use the
+ generated build script and also how the script works so you can build your own script.</p>
+ </section>
+ <section>
+ <title>Using the generated build scripts</title>
+ <p>The Wsdl2Java tool generates an Ant build script that is used to compile and deploy your WS-Resource. The script is located in the
+ output directory under the subdirectory for your WS-Resource (e.g., <code>generated/</code>
+ <em>
+ <code>service_name</code>
+ </em>).</p>
+ <p>To compile and deploy using the Ant script</p>
+ <ol>
+ <li>In your output directory, edit build.properties and modify the <code>wsrf.webapp.dir</code>. If you are using
+ Tomcat and have <code>CATALINA_HOME</code> set, you do not need to modify this property.</li>
+ <li>From a command prompt, change directories to <code>generated/</code>
+ <em>
+ <code>service_name</code>
+ </em>
+ </li>
+ <li>Run:</li>
+ </ol>
+ <source><![CDATA[
+ ant compile deploy ]]></source>
+ <p>Start Tomcat and verify that the service is deployed by going to
+ <a href="http://localhost:8080/wsrf/services">http://localhost:8080/wsrf/services</a>
+ </p>
+ </section>
+ <section id="steps">
+ <title>Manually Deploying your Service</title>
+ <p>In this section we will describe how to manually deploy your service. We will describe each step in the process.</p>
+ <ol>
+ <li>
+ <strong>Copy your WSDL file.</strong>
+ <p>Your WSDL file needs to be copied to an appropriate location in the webapp. We recommend you put it in the
+ <code>wsrf/WEB-INF/classes/wsdl</code> directory. This allows Axis to reference it from the classpath and avoids the need to
+ hard-code a location on your file system. This location is used when registering the service in the
+ <code>server-config.wsdd</code> file.
+ </p>
+ </li>
+ <li>
+ <strong>Copy your classes.</strong>
+ <p>You will need to copy any .class files, generated by Wsdl2Java or hand written, to the <code>wsrf/WEB-INF/classes/</code> directory so that your service can be created by Axis and Apache WSRF.</p>
+ </li>
+ <li>
+ <strong>Update the jndi-config.xml file.</strong>
+ <p>The jndi-config.xml contains information about your service, resource, and home class. This information is necessary for
+ Apache WSRF to create your home and handle requests for your service. It will setup the in-memory JNDI context for your classes.
+ Here is the entry for the FileSystem example:</p>
+ <source><![CDATA[ <service name="filesystem">
+ <resource name="home" type="example.filesystem.FileSystemHome">
+ <resourceParams>
+ <parameter>
+ <name>baseWebappUrl</name>
+ <value>http://$IP_ADDRESS$:8080/wsrf</value>
+ </parameter>
+ <parameter>
+ <name>serviceClassName</name>
+ <value>example.filesystem.FileSystemService</value>
+ </parameter>
+ <parameter>
+ <name>resourceClassName</name>
+ <value>example.filesystem.FileSystemResource</value>
+ </parameter>
+ <parameter>
+ <name>wsdlTargetNamespace</name>
+ <value>http://ws.apache.org/resource/example/filesystem</value>
+ </parameter>
+ <parameter>
+ <name>resourceIdentifierReferenceParameterName</name>
+ <value>{http://ws.apache.org/resource/example/filesystem}ResourceIdentifier</value>
+ </parameter>
+ </resourceParams>
+ </resource>
+ </service>]]></source>
+ <p>The<code> name</code> attribute is a unique name in the config file to denote your service in JNDI. The resource "name" attribute is
+ used for locating your home instance, and is named <code>home</code>. Notice <code>serviceClassName</code> points to the
+ clasname for the service class. The same is said for the <code>resourceClassName</code>. The <code>wsdlTargetNamespace
+ </code> is the target namespace from your WSDL.
+ </p>
+ <p>The <code>baseWebappUrl</code> parameter is used to define the URL of your Web application. You can include a static host, or as an
+ alternative, you can use the following markers which are replaced at runtime:
+ </p>
+ <ul>
+ <li>
+ <code>$IP_ADDRESS$</code> - An attempt is made to determine the IP address at runtime. (Do not use on multi-homed systems).</li>
+ <li>
+ <code>$HOST_NAME$</code> - An attempt is made to determine the host name at runtime.</li>
+ </ul>
+ <p>The <code>resourceIdentifierReferenceParameterName</code> parameter represents the name of the WS-Addressing-header that is used to
+ extract a unique resource identifier to lookup a specific WS-Resource instance. This value should be a QName that includes the local
+ reference parameter name in the format <em><code>{namespaceURI}localPart</code></em>, where namesapaceURI and localPart are the namespace and URI and local
+ part of the qualified name of the reference paramater that should contain the resource identifier. If you omit this entry, it is assumed that the service is a
+ <strong><code>SINGLETON</code></strong> service and no resource id is expected in the
+ WS-Addressing headers.
+ </p>
+ </li>
+ <li>
+ <strong>Update the server-config.wsdd file</strong>
+ <p>The <code>server-config.wsdd</code> file is the configuration file for the Axis SOAP engine,
+ which is bundled with Apache WSRF. This file is located in the <code>wsrf/WEB-INF/</code> directory.
+ See the <a href="ext:ws.apache.org/axis">Axis</a> documentation for complete instructions about <code>server-config.wsdd</code>
+ </p>
+ <p>The file contains a deployment entry for each Web service. For example, the FileSystem service example is:
+ </p>
+ <source><![CDATA[ <service name="filesystem" provider="java:WSRF" style="document" use="literal">
+ <wsdlFile>/wsdl/FileSystem.wsdl</wsdlFile>
+ <requestFlow>
+ <handler type="java:org.apache.axis.handlers.JAXRPCHandler">
+ <parameter name="className" value="org.apache.axis.message.addressing.handler.AxisServerSideAddressingHandler"/>
+ <parameter name="referencePropertyNames" value="*"/>
+ </handler>
+ </requestFlow>
+ </service>]]></source>
+ <p>The service <code>name</code> attribute is the endpoint name and should be the same as the port's <code>name</code> attribute
+ from your WSDL file. This will ensure people consuming your WSDL will be able to invoke your service.
+ </p>
+ <p>Notice the entry for <code>wsdlFile</code> which points to the <code>/wsdl/FileSystem.wsdl</code>.
+ This translates to the wsdl directory under the <code>WEB-INF/classes</code> directory.
+ </p>
+ <p>The last part is the <code>requestFlow</code>. This xml fragment is necessary to ensure the
+ requests are routed through the WS-Addressing handler. This is static and should
+ always be present. We did not define it globally in case there were other services
+ defined which will not use WS-Addressing.
+ </p>
+ </li>
+ </ol>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/home.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/home.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/home.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/home.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Writing a Home class</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <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
+ 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>
+ </section>
+ <section id="class-declaration">
+ <title>Class Declaration</title>
+ <p>The generated home class extends <code>AbstractResourceHome</code>. Extending <code>AbstractResourceHome</code>
+ 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.
+ </p>
+ <p>The <code>FileSystemHome</code> class extends <code>AbstractResourceHome</code> and implements <code>Serializable</code>:</p>
+ <source>public class FileSystemHome
+ extends AbstractResourceHome
+ implements Serializable</source>
+ <note>Many of the operations in the <code>AbstractResourceHome</code> may be overridden in your Home
+ class, if you have a need to modfify or extend the base class' functionality.</note>
+ </section>
+ <section id="ops">
+ <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 to create and add two resource instances:</p>
+ <source>public void init() throws Exception
+ {
+ super.init();
+ add( createInstance( LVOL1_ID ) );
+ add( createInstance( LVOL2_ID ) );
+ }</source>
+ <p>The <code>createInstance()</code> method:</p>
+ <ul>
+ <li>Creates an instance of the resource.</li>
+ <li>Sets an endpoint reference on the resource.</li>
+ <li>Calls <code>init()</code> on the resource.</li>
+ </ul>
+ <note>If you choose to not use the <code>createInstance()</code> method (e.g. if you have a non-empty constructor), then you must manually set the EPR then call
+ the <code>init()</code> method on the resource. The generated home class contains a utility method from the <code>AbstractResourceHome</code> that can be used
+ to build an EPR.</note>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/index.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/index.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/index.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/index.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,95 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>WSRF Developer Guide</title>
+ </header>
+ <body>
+ <section>
+ <title>About this Guide</title>
+ <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</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="site:p_overview">Pubscribe</a> and <a href="site:m_overview">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>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>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>The WS-ServiceGroup specification is currently not implemented in Apache WSRF.</note>
+ </li>
+ <li>WS-BaseFaults (WSRF-BF) - Defines a standard format for SOAP faults thrown by WSRF services.</li>
+ </ul>
+ </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>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>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>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/metadata.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/metadata.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/metadata.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/metadata.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,114 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Adding Service Metadata</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>Web services may have various metadata associated with them (e.g. the WSDL for the service or a set of Topic Space documents). The
+ <a href="http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-metadataexchange.pdf">WS-MEXWS-Metadata Exchange</a> specification (defined by Microsoft
+ and other industry contributors) defines operations that can be provided by services to allow clients to retrieve these metadata documents.
+ </p>
+ </section>
+ <section>
+ <title>Define the Operations</title>
+ <p>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 <code>portType</code> and <code>binding</code> sections.
+ </p>
+ <source><![CDATA[
+<portType name="MyPortType">
+ ...
+ <operation name="GetMetadata" >
+ <input message="mex:GetMetadataMsg" wsa04:Action="http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadata/Request" />
+ <output message="mex:GetMetadataResponseMsg" wsa04:Action="http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadata/Response" />
+ </operation>
+
+ <operation name="Get" >
+ <input message="mex:GetMsg" wsa04:Action="http://schemas.xmlsoap.org/ws/2004/09/mex/Get/Request" />
+ <output message="mex:GetResponseMsg" wsa04:Action="http://schemas.xmlsoap.org/ws/2004/09/mex/Get/Response" />
+ </operation>
+</portype>
+
+<binding name="MySoapHttpBinding">
+ ...
+ <operation name="GetMetadata" >
+ <soap:operation style="document"/>
+ <input>
+ <soap:body use="literal"/>
+ </input>
+ <output>
+ <soap:body use="literal"/>
+ </output>
+ </operation>
+
+ <operation name="Get" >
+ <soap:operation style="document"/>
+ <input>
+ <soap:body use="literal"/>
+ </input>
+ <output>
+ <soap:body use="literal"/>
+ </output>
+ </operation>
+</binding>]]></source>
+ </section>
+ <section>
+ <title>Modify the JNDI Configuration File</title>
+ <p>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.</p>
+ <p>To update the JNDI configuration file to include metadata information:</p>
+ <ol>
+ <li>Using a text editor, open <code>jndi-config.xml</code> in the <code>WEB-INF/classes</code> directory.</li>
+ <li>Add the following JNDI resource block to the service, for which you would like to associate metadata:
+ <source><![CDATA[
+<service name="myService">
+ <resource name="metadata" type="org.apache.ws.util.jndi.tools.MetadataConfigImpl">]]></source>
+ <p>The <code>org.apache.ws.util.jndi.tools.MetadataConfigImpl</code> object containing the metadata is available via JNDI using a Context lookup of
+ <code>wsrf/services/{service_name}/metadata</code> - i.e. <code>ctx.lookup("wsrf/services/sushi/metadata");</code>
+ </p>
+ </li>
+ <li>In the metadata resource block, add a<code> metadataConfig</code> element that contains metadata configurations. The configuration includes a <code>dialect</code>
+ 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.<source><![CDATA[
+<resource name="metadata" type="org.apache.ws.util.jndi.tools.MetadataConfigImpl">
+ <metadataConfig>
+ <!-- classpath -->
+ <metadata dialect="http://www.w3.org/2001/XMLSchema" identifier="http://ws.apache.org/resource/properties/test/sushi_classpath">
+ <location>org/apache/ws/resource/properties/SushiProperties.xsd</location>
+ </metadata>
+
+ <!-- file -->
+ <metadata dialect="http://schemas.xmlsoap.org/wsdl/" identifier="http://ws.apache.org/resource/properties/test/sushi_wsdl">
+ <location>C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.wsdl</location>
+ </metadata>
+
+ <!-- http url -->
+ <metadata dialect="http://www.w3.org/2001/XMLSchema" identifier="http://ws.apache.org/resource/properties/test/sushi_url">
+ <location>http://localhost:8080/wsrf/SushiProperties.xsd</location>
+ </metadata>
+
+ <!-- file url -->
+ <metadata dialect="http://www.w3.org/2001/XMLSchema" identifier="http://ws.apache.org/resource/properties/test/sushi_fileurl">
+ <location>file://C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.xsd</location>
+ </metadata>
+
+ <!-- EndpointReference -->
+ <metadata dialect="http://schemas.xmlsoap.org/ws/2004/08/addressing" identifier="http://ws.apache.org/resource/properties/test/sushi_epr">
+ <reference xmlns:wsa04="http://schemas.xmlsoap.org/ws/2004/08/addressing">
+ <wsa04:Address>http://localhost:8080/wsrf/services/sushi</wsa04:Address>
+ <wsa04:ReferenceProperties>
+ <sushi:ResourceIdentifier xmlns:sushi="http://ws.apache.org/resource/properties/test/sushi">1</sushi:ResourceIdentifier>
+ </wsa04:ReferenceProperties>
+ </reference>
+ </metadata>
+ </metadataConfig>
+</resource>]]></source>
+ </li>
+ <li>Save and close jndi-config.xml.</li>
+ <li>Restart Tomcat if it is already started.</li>
+ </ol>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/resource.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/resource.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/resource.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/resource.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,68 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Writing a Resource Class</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>The resource class is the stateful instance-representation of your Web service.
+ The resource maintains the resource <code>id</code> and the <code>ResourcePropertySet</code>. The resource <code>id</code> is
+ the unique identifier for an instance of your Web service. It allows you to have multiple
+ resource instances, each with their own state, fronted by the same Web service.
+ The stateful properties are represented by the <code>ResourcePropertySet</code>. The <code>ResourcePropertySet</code>
+ is the Java representation of the Resource Properties document defined in the schema section
+ of your WSDL file.
+ </p>
+ <p>When a request is made for a Web service, it is expected to contain a WS-Addressing
+ header which contains the resource <code>id</code>. When Apache WSRF receives the request it
+ 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 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>
+ <section id="class-declaration">
+ <title>Class Declaration</title>
+ <p>When declaring your Resource class you MUST implement <code>org.apache.ws.resource.Resource</code> which
+ provides the necessary operations for dealing with the <code>ResourcePropertySet</code> and the
+ resource's <code>id</code>.
+ </p>
+ <note>The resource<code> id</code> is a custom WS-Addressing header element which you will define in your configuration
+ information for your service.</note>
+ <p>Optionally, you may also implement <code>PersistentResource</code>, for providing hooks for persistence,
+ and <code>ScheduledResourceTerminationResource</code>, for adding the ability to schedule when the resource
+ should be terminated.
+ </p>
+ <p>The <code>FileSystemResource</code> class declaration is as follows:</p>
+ <source>public class FileSystemResource extends
+ AbstractFileSystemResource</source>
+ <p>Notice that we've extended a base abstract class. This allows us to focus solely on the <code>init()</code> operation for registering callback objects and initializing the values of our ResourceProperties.
+ </p>
+ <p>The <code>AbstractFileSystemResource</code> class implements <code>Resource</code>, <code>PropertiesResource</code>, and
+ <code> ScheduledResourceTerminationResource</code>. We've "abstracted" the non-user specific code to the abstract class so that the user can focus on
+ their initialization.
+ </p>
+ </section>
+ <section id="vars">
+ <title>Instance Variables</title>
+ <p>The instance variables of <code>AbstractFileSystemResource</code> should include the resource <code>id</code> and the
+ <code>ResourcePropertySet</code>. The <code>ResourcePropertySet</code> is the object representation of the resource
+ properties document associated with this resource instance.</p>
+ <note>Since it is not a requirement to have resource properties in your service,
+ there is a <code>PropertiesResource</code> interface to denote that properties are being exposed.</note>
+ </section>
+ <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
+ <code>init()</code>and <code>destroy()</code> operations
+ which allow you to initialize or clean up your resource.
+ </p>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/service.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/service.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/service.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/service.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,190 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Writing a Service Class</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>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.
+ </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 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">
+ <title>What classes will need to be written?</title>
+ <p>The provided example FileSystem includes a <code>FileSystemService</code> class.
+ The FileSystemService extends <code>AbstractFileSystemService</code>, which contains
+ 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>, 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
+ class to separate 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 <code>example.filesystem.AbstractFileSystemService</code> 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 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.
+ </p>
+ <p>The <code>AbstractFileSystemService</code> 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 <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-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>
+ </strong> and
+ <strong>
+ <code>org.apache.ws.resource.lifetime.porttype</code>
+ </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 Apache WSRF services must implement the <code>WsrfService</code> 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:</p>
+ <source> /**
+ * 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( );</source>
+ <p>The <code>getMethodNameMap()</code> 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
+ <code>ServiceSoapMethodName</code> and add mappings for your operations.
+ </p>
+ <p>The <code>getResourceContext()</code> 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<code> init()</code> method is provided to give you an opportunity to initialize members for your Service
+ (e.g. <code>ServiceSoapMethodName </code>)</p>
+ </section>
+ <section id="classvars">
+ <title>Class Variables</title>
+ <p>The class variables which should be defined are:</p>
+ <ol>
+ <li>
+ <strong>
+ <code>TARGET_NSURI</code>
+ </strong> - The target namespace of your sevice's WSDL file.</li>
+ <li>
+ <strong>
+ <code>TARGET_NSPREFIX</code>
+ </strong> - The target prefix to be associated with your service's namespace.</li>
+ </ol>
+ <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 are constants that other classes may need to access.</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 <code>AbstractFileSystem</code> class, we see the operations
+ defined for methods like: <code>getMultipleResourceProperties(..)</code>. 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 <code>GetMultipleResourcePropertiesProvider</code> 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>
+ <code>org.apache.ws.resource.properties.porttype.impl</code>
+ </strong> and
+ <strong>
+ <code>org.apache.ws.resource.lifetime.porttype.impl</code>
+ </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="service">
+ <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.
+ </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>:
+ </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 implement the <code>XmlObject</code> interface, since
+ all XmlBeans implement this interface.</p>
+ </section>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/singleton.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/singleton.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/singleton.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/singleton.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,43 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Creating a Singleton Service</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>You can create a singleton service if only a single instance of a resource is required. If a service is a singleton, no resource ID parameter is expected in the
+ header of requests sent to the service. To create a singleton service, you must create a single instance of the resource in the generated home class and modify the deployed
+ jndi-config.xml file.
+ </p>
+ </section>
+ <section>
+ <title>Create a Single Instance</title>
+ <p>Resource instances are created in the service's home class. For a singleton, specify an identifier of <code>null</code> when you call <code>createInstance()</code>. This
+ ensures that only a single instance of the resource is created. For example:</p>
+ <source><![CDATA[public void init() throws Exception
+ {
+ super.init();
+
+ HostResource host = (HostResource) createInstance( null );
+ add( host );
+ } ]]></source>
+ </section>
+ <section>
+ <title>Modify the JNDI Configuration File</title>
+ <p>To update the JNDII configuration file for a singleton service:</p>
+ <ol>
+ <li>Using a text editor, open <code>jndi-config.xml</code> in the <code>WEB-INF/classes</code> directory.</li>
+ <li>From the <code><![CDATA[<service name="your_service">]]></code> block, remove the <code>resourceIdentifierReferenceParameterName</code> parameter.
+ This parameter is not required for a singleton. Removing this entry ensures that Apache WSRF does not look for a resource id in the
+ WS Addressing header.</li>
+ <li>Save and close jndi-config.xml.</li>
+ <li>Restart Tomcat if it is already started.
+ <note>The service entry in jndi-config is only present if the service has been deployed.</note>
+ </li>
+ </ol>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/validate.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/validate.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/validate.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/validate.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Schema Validation</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>All requests sent to the resource invocation framework are validated against any defined schemas types which have corresponding XMLBean classes located on the
+ classpath. When validation fails, a fault that contains a detailed description of exactly what is wrong with the XM is returned to the client. Request validation is performed using
+ XMLBeans, which uses an in-memory binary schema store. If the utmost performance is required, request validation can be disabled.
+ </p>
+ </section>
+ <section>
+ <title>Disabling Schema Validation</title>
+ <p>Schema validation is enabled by default. This means that all requests are validated. If you would like to disable this feature, you must set the
+ <code>validateRequestXml</code> system property to <code>false</code>. The property must be set as a Java property before starting the container that is hosting
+ Apache WSRF. For example:</p>
+ <source>
+ -DvalidateRequestXml=false</source>
+ <p>If you are using Tomcat, you can set this property in the <code>JAVA_OPTS</code> variable before starting Tomcat. For example:</p>
+ <source>
+ set JAVA_OPTS=-DvalidateRequestXml=false
+ catalina.bat run</source>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsdl_tool.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsdl_tool.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsdl_tool.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsdl_tool.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,143 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Using Wsdl2Java</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <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 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
+ 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
+ are automatically generated. You can use the tool directly or you can use an Ant task.
+ </p>
+ </section>
+ <section>
+ <title>Ant Task</title>
+ <p>The Wsdl2Java tool can be invoked using the <code>wsdl2Java</code> Ant task (<code>org.apache.ws.resource.tool.Wsdl2JavaTask</code>). The
+ <code>INSTALL_DIR/template/build.xml</code> script contains a target that already implements this task.</p>
+ <p>To use the target:</p>
+ <ol>
+ <li>copy INSTALL_DIR/template/build.xml and build.properties to any directory. This directory will be referred to as <code>WORK_DIR</code>.</li>
+ <li>Using a text editor, open <code>WORK_DIR/build.properties</code>.</li>
+ <li>Uncomment the <code>wsrf.webapp.dir</code> property and set it to the location where the WSRF Web application is installed. If you are using
+ Tomcat and have the <code>CATALINA_HOME</code> environment variable set, you do not need to modify this property.</li>
+ <li>Uncomment and modify the proxy settings if you require a proxy to connect to external Web sites.</li>
+ <li>Copy your WSRF WSDL to <code>WORK_DIR</code>. If your WSDL depends on a schema that is not accessible over the network, you must copy the
+ schema to this directory as well.</li>
+ <li>From a command prompt, change directories to <code>WORK_DIR</code>.</li>
+ <li>Run the following command.
+ <source>ant generate</source>
+ <p>Check <code>WORK_DIR/generated</code> to see the generated files.
+ </p>
+ </li>
+ </ol>
+ <section>
+ <title>Task Definition</title>
+ <p>The task is defined as follows :</p>
+ <source><![CDATA[
+<taskdef name="wsdl2Java"
+ classname="org.apache.ws.resource.tool.Wsdl2JavaTask"
+ classpath="path/to/wsrf.jar" /> ]]></source>
+ <p>
+ <strong>Parameters</strong>
+ </p>
+ <p>The task takes the following parameters:</p>
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
+ </tr>
+ <tr>
+ <td>wsdl</td>
+ <td>Enter the full path to a WSRF WSDL file.</td>
+ <td>Yes, unless a <code>wsdls</code> parameter is used. </td>
+ </tr>
+ <tr>
+ <td>wsdls</td>
+ <td>Entered as a nested element following the rules of fileset. This parameter is used instead of the <code>wsdl</code> parameter to indicate multiple
+ WSRF WSDLs to be converted.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>classpath</td>
+ <td>The classpath to be passed to the XMLBeans schema compiler. The classpath should reference the all the jars in the
+ <code>INSTALL_DIR/wsrf/webapp/lib</code> and <code>/classes</code> directories.</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>classpathref</td>
+ <td>Adds a classpath, given as reference to a path defined elsewhere.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>outputdir</td>
+ <td>Enter a directory where the generated files will be placed.</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>verbose</td>
+ <td>Enter <code>true</code> to increase build message output.</td>
+ <td>No, default is <code>false</code>
+ </td>
+ </tr>
+ <tr>
+ <td>proxyHost</td>
+ <td>Enter the Host IP address of a proxy that is used to connect to the Internet.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>proxyPort</td>
+ <td>Enter the Port number of a proxy that is used to connect to the Internet.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>nonProxyHosts</td>
+ <td>Enter the Host IP address separated by "|" to indicate Hosts that do not require a proxy.</td>
+ <td>No</td>
+ </tr>
+ </table>
+ <p>
+ <strong>Example</strong>
+ </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" />
+ <path id="wsrf.classpath.id">
+ <pathelement location="${wsrf.webapp.dir}/WEB-INF/classes" />
+ <fileset dir="${wsrf.webapp.dir}/WEB-INF/lib" includes="*.jar" />
+ </path>
+
+ <taskdef name="wsdl2Java" classname="org.apache.ws.resource.tool.Wsdl2JavaTask" classpath="wsrf.classpath.id" />
+
+ <wsdl2Java wsdl="path/to/your.wsdl"
+ outputdir="generated"
+ classpath="wsrf.classpath.id" />]]></source>
+ <p>If you want to generate the files for multiple WSDLs, you can use:</p>
+ <source><![CDATA[
+
+ <wsdl2Java outputdir="generated" classpath="wsrf.classpath.id" />
+ <wsdls dir="path/to/wsdls/">
+ <include name="**/*.wsdl" />
+ </wsdls>
+ </wsdl2Java>]]></source>
+ </section>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsrf_wsdl.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsrf_wsdl.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsrf_wsdl.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsrf_wsdl.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,135 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Composing a WSRF WSDL</title>
+ </header>
+ <body>
+ <section>
+ <title>Using the WSRF WSDL Template</title>
+ <p>Resources are exposed as WSRF WS-Resources using the Web Services Description Language (WSDL). The WSDL must
+ conform to the conventions as described in the <a href="site:wsrf">WSRF Specifications</a>. To make it easier to write a
+ WSRF WSDL, Apache WSRF provides a template WSDL that can be used as a starting point. The template saves a good deal of time
+ and is less error-prone than writing a WSRF-compliant WSDL from scratch.
+ </p>
+ <p>To use the template:</p>
+ <ol>
+ <li>Using a text or XML editor, open <code>INSTALL_DIR/template/_TEMPLATE_.wsdl</code>.</li>
+ <li>Save the file with a new name (e.g., <em>nameOfYourService</em>.wsdl).</li>
+ <li>Modify your WSDL based on the instructions in the template and the information below.</li>
+ </ol>
+ <warning>Do not modify the original template file.</warning>
+ </section>
+ <section>
+ <title>Defining the WSRF PortType</title>
+ <p>A WSRF WSDL should contain only one portType. The portType aggregates operations from WSRF specification-defined portTypes
+ 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>
+ </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
+ uncomment the blocks corresponding to whichever optional portTypes you want your WS-Resource to support.
+ </p>
+ <section>
+ <title>WS-ResourceProperties (WSRF-RP) PortTypes</title>
+ <table>
+ <tr>
+ <th>PortType</th>
+ <th>Operations</th>
+ <th>Properties</th>
+ </tr>
+ <tr>
+ <td>GetResourceProperty</td>
+ <td>GetResourceProperty</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>GetMultipleResourceProperties</td>
+ <td>GetMultipleResourceProperties</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>SetResourceProperties</td>
+ <td>SetResourceProperties</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>QueryResourceProperties</td>
+ <td>QueryResourceProperties</td>
+ <td/>
+ </tr>
+ </table>
+ <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>
+ <table>
+ <tr>
+ <th>PortType</th>
+ <th>Operations</th>
+ <th>Properties</th>
+ </tr>
+ <tr>
+ <td>ImmediateResourceTermination</td>
+ <td>Destroy</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>ScheduledResourceTermination</td>
+ <td>SetTerminationTime</td>
+ <td>CurrentTime,
+ <br/>TerminationTime
+ </td>
+ </tr>
+ </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>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 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 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>
+ </section>
+ </section>
+ <section>
+ <title>Adding Custom Operations</title>
+ <p>Custom operations can be added to the WSRF portType. To do so,
+ you will have to define message types, messages, and operations, as you would
+ for any WSDL. It is recommended that, when defining your custom operations,
+ you adhere to the rules defined by
+ <a href="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#description">section 5 of the WS-I Basic Profile</a>.
+ This will ensure maximum interoperability for your WS-Resource.
+ </p>
+ </section>
+ <section>
+ <title>Defining Resource Properties</title>
+ <p>Resource properties are defined in the types/schema section of the WSDL file. In addition to defining
+ custom resource-specific properties, you may also need to add properties that are required by certain
+ specification-defined portTypes. For example, the WSRF-RL ScheduledResourceTermination portType requires
+ two properties (see above). Chapter 4 of the
+ <a href="http://docs.oasis-open.org/wsrf/2004/11/wsrf-WS-ResourceProperties-1.2-draft-05.pdf">WSRF-RP specification</a>
+ explains how to define resource properties.
+ </p>
+ <p>If you have copied the WSDL template file as described above, your WSDL file
+ already contains a resource properties document definition. If your WS-Resource
+ 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), uncomment the xsd <code>any</code> element.
+ </p>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/getting_started.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/getting_started.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/getting_started.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/getting_started.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,87 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Getting Started with Apache WSRF</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>The topics in this section detail how to install Apache WSRF and use the quick demonstration to verify the installation as well
+ as exercise some of the features that are included in the release. It is suggested that you complete these sections before
+ starting any development work. Once you get a good feel for the example in the demonstration, you can recreate it by
+ completing the <a href="site:tut">tutorial</a>.</p>
+ <p>The tutorial takes a step-by-step approach to learning Apache WSRF. It highlights the most common procedures that are used
+ to create WSRF-compliant Web services for resources. The tutorial also includes steps for deploying Apache WSRF Web
+ services.</p>
+ <p>Lastly, refer to the <a href="site:dev">Developer Guide</a> for basic and advanced tasks as well as general information
+ about Apache WSRF. In addition, much of the information that is covered in the demonstration and the tutorial is discussed in more
+ detail in the Developer Guide.</p>
+ </section>
+ <section id="install">
+ <title>Installation</title>
+ <p> Apache WSRF is packaged as a Web application. In particular, it is an Apache Axis-based Web application with
+ additional functionality that is required to implement the WSRF family of specifications.</p>
+ <p>To run and install Apache WSRF, you must first:</p>
+ <ul>
+ <li>install Apache Tomcat or a similar Web container. The documentation assumes Tomcat and refers to the Tomcat
+ home directory (e.g., <code>c:\jakarta-tomcat-4.1.30</code>) as <code>TOMCAT_HOME</code>. In addition, it is assumed
+ that Tomcat is configured to listen at the default HTTP port (8080).</li>
+ <li>install Apache Ant 1.6.X and include its <code>bin</code> directory in the <code>PATH</code> environment variable. Set an
+ ANT_HOME environment variable to the Ant installation directory.
+ </li>
+ </ul>
+ <p>To install Apache WSRF:</p>
+ <ol>
+ <li>Download the Apache WSRF <a href="site:releases">binary distribution</a>.</li>
+ <li>Unzip the Apache WSRF distribution to a location on your computer. This location is referred to as
+ <code>INSTALL_DIR</code>.</li>
+ <li>From <code>INSTALL_DIR</code>, copy the <code>webapps/wsrf</code> directory to
+ <code>TOMCAT_HOME/webapps</code>.</li>
+ <li>Start Tomcat. If Tomcat is already started, you must restart it.</li>
+ <li>Using a browser, go to <a href="http://localhost:8080/wsrf">http://localhost:8080/wsrf</a>. The Apache WSRF welcome
+ page displays.</li>
+ <li>Click <a href="http://localhost:8080/wsrf/services">View</a>. The list of
+ deployed Web services displays. Two services are deployed: <code>AdminService</code>, and
+ <code>Version</code>. The <code>AdminService</code> and <code>Version</code> services are default Apache-Axis
+ services.</li>
+ <li>Click on the respective WSDL links to view and ensure that the WSDL for the services are published.</li>
+ </ol>
+ </section>
+ <section id="qd">
+ <title>Quick Demonstration</title>
+ <p>The Quick Demonstration shows some of the features and implementation details of Apache WSRF. The demo uses an
+ example that is included in the distribution (<code>INSTALL_DIR/examples/filesystem</code>). The example represents a UNIX file
+ system resource whose management capabilities are exposed as a WSRF-compliant Web service.</p>
+ <note>The <a href="site:tut">tutorial</a> provides a step-by-step approach for exposing the management capabilities of the file
+ system resource. In essence, the tutorial builds and deploys the example that is used in this demo.</note>
+ <p>Complete the following steps:</p>
+ <ol>
+ <li>Using a text editor, open <code>INSTALL_DIR/examples/filesystem/build.properties</code>.</li>
+ <li>Change the <code>wsrf.webapp.dir</code> property and set it to the location where the Apache WSRF Web application is installed.
+ If you are using Tomcat and have <code>CATALINA_HOME</code> set, you do not need to modify this property.</li>
+ <li>Uncomment and modify the proxy settings if you require a proxy to connect to external Web sites.</li>
+ <li>Save and close build.properties.</li>
+ <li>Open a command prompt and change directories to <code>INSTALL_DIR/examples/filesystem</code>.</li>
+ <li>Run the following command:
+ <p>
+ <code>ant compile deploy</code>
+ </p>
+ </li>
+ <li>Start Tomcat, or restart it if it is already started.</li>
+ <li>Using a browser, go to <a href="http://localhost:8080/wsrf/services">
+ http://localhost:8080/wsrf/services</a> and verify that the filesystem service is deployed.
+ </li>
+ <li>In this step, an Ant-based SOAP client that is included in the distribution is used to send a SOAP request to the filesystem Web service.
+ The request uses the <code>GetMultipleResourceProperties</code> operation to return a list of resource properties for the filesystem
+ resource. From a command prompt change directories to <code>INSTALL_DIR/examples/filesystem</code> directory and run the
+ following command:
+ <source><![CDATA[
+
+ant -f soapclient.xml -Durl=http://localhost:8080/wsrf/services/filesystem -Dxml=requests/GetMultipleResourceProperties.soap]]></source>
+ <br/>You may also try other request messages in the <code>requests</code> sub-directory.</li>
+ </ol>
+ </section>
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: muse-commits-unsubscribe@ws.apache.org
For additional commands, e-mail: muse-commits-help@ws.apache.org