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/28 18:46:07 UTC
svn commit: r225814 - in
/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide: deploy.xml
home.xml metadata.xml singleton.xml wsrf_wsdl.xml
Author: jruzzi
Date: Thu Jul 28 09:46:01 2005
New Revision: 225814
URL: http://svn.apache.org/viewcvs?rev=225814&view=rev
Log:
updated content
Added:
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/singleton.xml
Modified:
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/deploy.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml
webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml
Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/deploy.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/deploy.xml?rev=225814&r1=225813&r2=225814&view=diff
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/deploy.xml (original)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/deploy.xml Thu Jul 28 09:46:01 2005
@@ -61,6 +61,10 @@
<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>
@@ -84,7 +88,14 @@
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>resourceIdentifierReferenceParameterName</code> represents the name of the WS-Addressing-header that is used to
+ <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>{target namespace}qualified name of a reference parameter</code>
Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml?rev=225814&r1=225813&r2=225814&view=diff
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml (original)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/home.xml Thu Jul 28 09:46:01 2005
@@ -8,13 +8,13 @@
<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
+ <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>
- <p>If you use the Wsdl2Java tool, the resource 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 class. 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 class.</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>
@@ -30,51 +30,16 @@
<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 Resource getInstance( ResourceContext resourceContext )</source>
- <p>The <code>getInstance(...)</code> operation provides the ability for you to intercept the request for
- retrieving an instance. In the FileSystem example, we use the operation to determine
- if the requested resource instance is a valid filesystems (i.e. one that is being managed
- via WSRF); if it is not, we throw an exception.</p>
- <source>public Resource getInstance( ResourceContext resourceContext )
- throws ResourceException,
- ResourceContextException,
- ResourceUnknownException
+ <source>public void init()</source>
+ <p>The <code>init()</code> operation can be used to initialize any instances at startup. In the FileSystem example, the <code>init()</code> method is used:</p>
+ <source>public void init() throws Exception
{
- ResourceKey key = resourceContext.getResourceKey();
- Resource resource = null;
- try
- {
- resource = find( key );
- }
- catch ( ResourceException re )
- {
- Object id = key.getValue();
- /**
- * Determine if the passed-in key is, in fact, something we expect.
- */
- if ( id.equals( "/dev/vg00/lvol1" ) || id.equals( "/dev/vg00/lvol2" ) )
- {
- try
- {
- resource = createInstance( key);
- }
- catch ( Exception e )
- {
- throw new ResourceException( e );
- }
- add( key, resource );
- }
- else
- {
- throw new ResourceUnknownException( id,
- resourceContext.getServiceName() );
- }
- }
- return resource;
+ super.init();
+ FilesystemResource lvol1Resource = (FilesystemResource) createInstance( LVOL1_ID );
+ add( lvol1Resource );
+ FilesystemResource lvol2Resource = (FilesystemResource) createInstance( LVOL1_ID );
+ add( lvol2Resource );
}</source>
- <p>Notice the method makes calls to <code>find(...) </code>and <code>createInstance(...)</code>. These operations are
- provided by the <code>AbstractResourceHome</code> superclass. They provide functions like caching and
- instantiating instances.</p>
<note>Many of the operations in the <code>AbstractResourceHome</code> may be overridden in your Home
class, if you have a need to extend its functionality.</note>
</section>
Added: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml?rev=225814&view=auto
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml (added)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/metadata.xml Thu Jul 28 09:46:01 2005
@@ -0,0 +1,113 @@
+<?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 use metadata to describe what other endpoints need to know to interact with them. In particular, the metadata for a Web service includes the
+ service's description (WSDL or schema). There are two operations that are not defined by the WSRF specification that can be used in your services 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.
+ </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 JDNI 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 JDNI 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.MetadataConfig">]]></source>
+ <p>The <code>org.apache.ws.util.jndi.tools.MetadataConfig</code> object containing the metadata is available via JNDI using a Context lookup of
+ <code>wsrf/services/{sevice_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 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.MetadataConfig">
+ <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://www.w3.org/2001/XMLSchema" identifier="http://ws.apache.org/resource/properties/test/sushi_file">
+ <location>C:/Projects/apache/wsrf/trunk/src/test/org/apache/ws/resource/properties/SushiProperties.xsd</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://www.w3.org/2001/XMLSchema" 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/wsrf/trunk/src/site/content/xdocs/dev_guide/singleton.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/singleton.xml?rev=225814&view=auto
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/singleton.xml (added)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/singleton.xml Thu Jul 28 09:46:01 2005
@@ -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 is expected in the
+ WS-Addressing header. 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, set the <code>createInstance</code> method to <code>null</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 JDNI configuration file for a singleton:</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.
+ 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>
Modified: webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml
URL: http://svn.apache.org/viewcvs/webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml?rev=225814&r1=225813&r2=225814&view=diff
==============================================================================
--- webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml (original)
+++ webservices/wsrf/trunk/src/site/content/xdocs/dev_guide/wsrf_wsdl.xml Thu Jul 28 09:46:01 2005
@@ -95,6 +95,13 @@
in the types/schema section of the WSDL file.
</p>
</section>
+ <section>
+ <title>Metadata Operations</title>
+ <p>The template contains two operations that are not defined by the WSRF specification that can be used in your service to retrieve metadata
+ 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>