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 [1/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...
Author: scamp
Date: Fri Jun 2 10:30:32 2006
New Revision: 411217
URL: http://svn.apache.org/viewvc?rev=411217&view=rev
Log: (empty)
Added:
webservices/muse/branches/1.0/src/site/content/xdocs/muse/
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/advertiser.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/client.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/debug.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/deploy.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/muws_topics.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/relationships.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl_tool.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/getting_started.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/site.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tabs.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/images/
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/images/back.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/images/next.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/mod_home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/mod_resource.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/mod_service.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/setup.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/test.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/webapp.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muse/tutorial/wsdl2java.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/client.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/consumer.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/debug.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/deploy.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/producer.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/subscription.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/dev_guide/wsdl_tool.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/getting_started.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/site.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tabs.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/images/
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/images/back.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/images/next.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/mod_home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/mod_resource.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/setup.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/test.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/webapp.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/pubscribe/tutorial/wsdl2java.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/callback.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/client.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/debug.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/deploy.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/metadata.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/resource.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/service.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/singleton.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/validate.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsdl_tool.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/dev_guide/wsrf_wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/getting_started.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/site.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tabs.xml_old
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/images/
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/images/back.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/images/next.gif (with props)
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/mod_home.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/mod_resource.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/setup.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/test.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/webapp.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/wsdl.xml
webservices/muse/branches/1.0/src/site/content/xdocs/wsrf/tutorial/wsdl2java.xml
Removed:
webservices/muse/branches/1.0/src/site/content/xdocs/getting_started.xml
Modified:
webservices/muse/branches/1.0/src/site/content/xdocs/index.xml
webservices/muse/branches/1.0/src/site/content/xdocs/muws.xml
webservices/muse/branches/1.0/src/site/content/xdocs/release_notes.xml
webservices/muse/branches/1.0/src/site/content/xdocs/site.xml
webservices/muse/branches/1.0/src/site/content/xdocs/tabs.xml
Modified: webservices/muse/branches/1.0/src/site/content/xdocs/index.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/index.xml?rev=411217&r1=411216&r2=411217&view=diff
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/index.xml (original)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/index.xml Fri Jun 2 10:30:32 2006
@@ -7,9 +7,8 @@
<body>
<section>
<title>Overview</title>
- <p>Muse is a Java implementation of the <a href="site:wsdm">Management Using Web Services (MUWS) 1.0 specifications</a>. Muse 1.0 utilizes
- <a href="ext:wsrf/">Apache WSRF</a> as its WS-ResourceFramework (WSRF) implementation and <a href="ext:pubscribe/">Apache Pubscribe</a> as its
- WS-Notification (WSN) implementation. Muse allows you to start from a MUWS-compliant WSDL file and generate a MUWS Web service which can be hosted inside of Axis or
+ <p>Muse is a Java implementation of the <a href="site:wsdm">Management Using Web Services (MUWS) 1.0 specifications</a>. Muse 1.0 contains a WS-ResourceFramework (WSRF) implementation (formerly Apache WSRF) and a
+ WS-Notification (WSN) implementation (formerly Apache Pubscribe). Muse allows you to start from a MUWS-compliant WSDL file and generate a MUWS Web service which can be hosted inside of Axis or
other SOAP engines.
</p>
</section>
@@ -17,10 +16,9 @@
<title>Features</title>
<p>Apache Muse includes the following features:</p>
<ul>
- <li>Apache WSRF's handler/service framework and WS-RP/WS-RL/WS-MeX portType implementations</li>
- <li>Apache Pubscribe's WS-BaseNotification portType implementation</li>
- <li>A WSDL to Java generator that generates the classes and configuration entries from a WSRF/WSN/WSDM WSDL that are required to deploy it as a service to the
- Apache WSRF framework</li>
+ <li>Handler/service framework and WS-RP/WS-RL/WS-MeX portType implementations</li>
+ <li>WS-BaseNotification portType implementation</li>
+ <li>A WSDL to Java generator that generates the classes and configuration entries from a WSRF/WSN/WSDM WSDL that are required to deploy it as a service to the Muse framework</li>
<li>Implementations of all (one :) MUWS-defined portTypes</li>
<li>Implementations of the MUWS-defined topics and interfaces for MUWS-defined types</li>
<li>An Advertiser service that is a notification producer for the MUWS-defined resource creation/destruction topics</li>
@@ -35,6 +33,13 @@
<li>(June 20, 2005) <a href="http://cvs.apache.org/dist/incubator/muse/snapshot/">Muse snapshot</a> is now available!</li>
<li>(May 25, 2005) <a href="http://cvs.apache.org/dist/incubator/muse/1.0-beta/">Muse 1.0 Beta</a> is now available!</li>
</ul>
+ </section>
+ <section>
+ <title>History</title>
+ <p>Much of the code in WSRF/WSN implementations are based on code from the GTK4 WSRF/WSN implementation that was donated by the Globus Consortium. This code was
+ refactored to make extensive use of Apache XMLBeans to add improved runtime schema type validation and to enable portability to SOAP engines other than Axis.
+ The original GTK4 WSRF/WSN code is checked in to SVN <a href="http://svn.apache.org/viewcvs.cgi/incubator/apollo/globus/">here</a>.
+ </p>
</section>
</body>
</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/advertiser.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/advertiser.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/advertiser.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/advertiser.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,97 @@
+<?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 the Resource Advertiser Service</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>The MUWS specification defines an Advertisement capability that provides a notification whenever a manageable resource is created or destroyed. The
+ capability includes no operations or properties, but contains four topics:</p>
+ <ul>
+ <li>
+ <code>ManageableResourceCreation</code>
+ </li>
+ <li>
+ <code>ManageableResourceDestruction</code>
+ </li>
+ <li>
+ <code>ManageabilityEndpointCreation</code>
+ </li>
+ <li>
+ <code>ManageabilityEndpointDestruction</code>
+ </li>
+ </ul>
+ <p>Muse implements these topics as part of the <code>ResourceAdvertiser</code> service that is deployed by default in Muse. Therefore, it does not have to be
+ defined in a MUWS WSDL. This ensures that these topics are always created without having to directly implement them in your WS Resource.
+ </p>
+ <note>Muse does not implement the <code>ManageabilityEndpointCreation</code> and <code>ManageabilityEndpointDestruction</code> topics.</note>
+ </section>
+ <section>
+ <title>Resource Advertiser Messages</title>
+ <p>Messages to subscribe to advertisement topics are sent to the <code>ResourceAdvertiser</code> service. This service is deployed by default when you deploy
+ the Muse Web application. The service utilizes the <code>Subscribe</code> and <code>GetCurrentMessage</code> operations that are defined in the
+ WS-BaseNotification specification and implemented in Apache Pubscribe. The service can also be used to send <code>GetResourceProperty</code> and
+ <code>GetMultipleResourceProperties</code> messages. These operations are defined in the WS-ResourceProperties specification and implemented in Apache
+ WSRF.
+ </p>
+ <p>The below requests demonstrate how to subscribe to the resource creation and destruction topics. The requests would be sent to the advertiser service (e.g. http://localhost:8080/muse/services/ResourceAdvertiser
+ </p>
+ <p>A selector can optionally be included in the subscribe requests to indicate that you are only interested in the creation or destruction of resources of a particular type.</p>
+ <section>
+ <title>Subscribe to Creation Notifications</title>
+ <source><![CDATA[
+<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:wsa03="http://schemas.xmlsoap.org/ws/2003/03/addressing">
+
+ <Header>
+ <wsa03:To mustUnderstand="1">http://localhost:8080/muse/services/ResourceAdvertiser</wsa03:To>
+ <wsa03:Action mustUnderstand="1">http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/Subscribe</wsa03:Action>
+ </Header>
+
+ <Body>
+ <wsnt:Subscribe xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd">
+
+ <wsnt:ConsumerReference>
+ <wsa03:Address>http://localhost:909/services/consumer</wsa03:Address>
+ </wsnt:ConsumerReference>
+
+ <wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete"
+ xmlns:muws-p2-topics="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml">muws-p2-topics:ManageabilityEndpointCreation/ManageableResourceCreation</wsnt:TopicExpression>
+
+ </wsnt:Subscribe>
+ </Body>
+
+</Envelope>]]></source>
+ </section>
+ <section>
+ <title>Subscribe to Destruction Notifications</title>
+ <source><![CDATA[
+<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:wsa03="http://schemas.xmlsoap.org/ws/2003/03/addressing">
+
+ <Header>
+ <wsa03:To mustUnderstand="1">http://localhost:8080/muse/services/ResourceAdvertiser</wsa03:To>
+ <wsa03:Action mustUnderstand="1">http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/Subscribe</wsa03:Action>
+ </Header>
+
+ <Body>
+ <wsnt:Subscribe xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd">
+
+ <wsnt:ConsumerReference>
+ <wsa03:Address>http://localhost:909/services/consumer</wsa03:Address>
+ </wsnt:ConsumerReference>
+
+ <wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete"
+ xmlns:muws-p2-topics="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml">muws-p2-topics:ManageabilityEndpointDestruction/ManageableResourceDestruction</wsnt:TopicExpression>
+
+ </wsnt:Subscribe>
+ </Body>
+
+</Envelope>]]></source>
+ </section>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/client.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/client.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/client.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/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>Muse 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 identifier to match the entry that is in the JNDI
+ configuration file and the resource identifier 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/muse/services/<em>your_service</em> -Dxml=./requests/Subscribe_updateMountPointProp.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/muse/dev_guide/debug.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/debug.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/debug.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/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>Muse 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 Muse 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 Muse 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/muse/dev_guide/deploy.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/deploy.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/deploy.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/deploy.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,147 @@
+<?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 Muse 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 scripts. The scripts compile and delploy your WS
+ Resource to the Muse Web application, which is an Apache-Axis Web application. This section describes how to use the
+ generated build scripts and also how the script works so you can build your own scripts.</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 you 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>from your output directory, edit build.properties and uncomment the <code>muse.webapp.dir</code> property and set it to the location where the Muse
+ 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>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/muse/services">http://localhost:8080/muse/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>muse/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>muse/WEB-INF/classes/</code> directory so that your service
+ can be created by Axis and Muse.</p>
+ </li>
+ <li>
+ <strong>Update the jndi-config.xml file.</strong>
+ <p>The jndi-config.xml contains information about your service, resource, home and resource identifier. This information is necessary for
+ Muse 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 that was used 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/muse</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 Muse. This file is located in the <code>muse/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/muse/dev_guide/home.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/home.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/home.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/home.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,55 @@
+<?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="ext:single">Creating a Singleton Service</a> in the Apache WSRF
+ documentation.</note>
+ <p>If you use the Wsdl2Java tool, the home class is automatically generated but will need to be 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 extend its 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:</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/muse/dev_guide/index.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/index.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/index.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/index.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,71 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Muse 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 Muse. 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 Muse.</p>
+ <note>Muse is tightly integrated with <a href="ext:wsrf">Apache WSRF</a> as its WSRF foundation and <a href="ext:pubscribe">Apache Pubscribe</a> as its WSN
+ foundation. While it is not required, it is a good idea to start with Apache WSRF and Apache Pubscribe to learn more about these respective foundations.
+ You should also consult the Apache WSRF and Apache Pubscribe documentation while completing the instructions in this document. All of the tasks required in Apache WSRF and
+ Apache Pubscribe are also required in Muse.
+ </note>
+ <p>The Developer guide often refers to different parts of the <a href="site:wsdm">Web Services Distributed Management (WSDM) 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 WSRF, Apache Pubscribe, 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>
+ </section>
+ <section>
+ <title>WSDM Overview</title>
+ <p>
+ <a href="site:wsdm">WSDM</a> is defined by the OASIS standards body and is comprised of two separate specifcations:
+ </p>
+ <ul>
+ <li>Management using Web Services (MUWS) - MUWS defines how to represent and access the manageability interfaces of resources as Web services. It is the
+ foundation of enabling management applications to be built using Web services and allows resources to be managed by many managers with one set of instrumentation. The
+ specification provides interoperable, base manageability for monitoring and control managers using Web services. WSDM MUWS is defined in two specifications,
+ MUWS Part 1, which defines the base architectural concepts and required components, and MUWS Part 2 which defines standard composeable support for manageability
+ capabilities.</li>
+ <li>Management of WebServices (MOWS)- MOWS defines the manageability model for managing Web services as a resource and how to describe and access that
+ manageability using MUWS.</li>
+ </ul>
+ <p>Muse is an implementation of both parts of the MUWS specification.</p>
+ </section>
+ <section>
+ <title>Conceptual Overview</title>
+ <p>Muse builds on top of Apache WSRF and Apache Pubscribe and provides three deliverables:</p>
+ <ul>
+ <li>APIs for MUWS management events, relationships, etc.</li>
+ <li>implementation of the <code>QueryRelationshipsByType</code> operation defined by the MUWS specification</li>
+ <li>an Advertiser service that exposes the MUWS-defined <code>ManageableResourceCreation</code> and <code>ManageableResourceDestruction</code> topics and
+ publishes notifications to those topics whenever any Resource instances are added or removed to any deployed MUWS services</li>
+ </ul>
+ <p>The MUWS specification defines a capability as a set of related operations, properties, and topics that a management resource may implement. The specification defines many
+ standard capabilities. Most of the standard capabilities include properties and/or topics, but not operations. There is only one capability that defines any operations, and it only
+ defines one. Hence, what Muse primarily provides is not implementations of operations, but rather implementations of the specification-defined topics that will automatically publish
+ notifications when the corresponding situation occurs. It also provides helper utility methods that can be used to easily add the various MUWS-defined topics to a producer
+ resourceâs topic set.
+ </p>
+ </section>
+ <section>
+ <title>Design-Time</title>
+ <p>A set of tools and integrations are provided that facilitate developing MUWS-compliant Web services. They are provided to help developers focus on
+ defining their WS Resource and Notification Topics without having to deal with low-level implementation details.</p>
+ <note>These tools and integrations are not required to create MUWS-compliant Web services, but are instead provided to save you time.</note>
+ <p>The tools and integrations include:</p>
+ <ul>
+ <li>A MUWS WSDL template for writing MUWS-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/muse/dev_guide/muws_topics.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/muws_topics.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/muws_topics.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/muws_topics.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,217 @@
+<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>MUWS-Specific Topics</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>Each resource that is configured to be a notification producer (implements the WSN <code>NotificationProducer</code> portType) is associated with a
+ topic set. The resource publishes notifications to a topic in the topic set. Notification consumers can then subscribe to a topic and receive notifications
+ from the resource. As the service developer of the notification producer resource, you are responsible for adding the topics you want to support to the topic set.
+ </p>
+ <p>
+ This section provides instructions for adding support to your managed resource for the various topics that are defined by MUWS.
+ The topics can be organized into three types:
+ </p>
+ <ul>
+ <li>Capability topics: Topics for each of the MUWS defined resource properties that indicate changed property events</li>
+ <li>Advertiser topics: Topics for resource creation and destruction events</li>
+ <li>Relationship topics: Topics for relationship created and deleted events</li>
+ </ul>
+ <note>For information on adding custom topics for your resource, see the <a href="site:p_producer">Notification Producer</a> section in the Apache Pubscribe
+ documentation.</note>
+ <p>Notification topics are added to the <code>init()</code> method of your service's resource class. If you used the Wsdl2Java tool, the resource class
+ (<em>
+ <code>service_name</code>
+ </em>
+ <code>Resource.java</code>) is automatically generated, but will need to modified. Initially, you should model your resource off of the included FileSystemResource
+ example to ensure that you write a valid resource class.
+ </p>
+ <p>The resource class is the stateful instance-representation of your Web service. In addition to notification topics, the resource class maintains the resource
+ <code>id</code> and the <code>ResourcePropertySet</code>. The <code>ResourcePropertySet</code> is the Java representation of the Resource Properties document
+ defined in the types section of your WSDL file.
+ </p>
+ <note>This section does not include complete instructions for initializing resource properties and adding them to the <code>ResourcePropertySet</code>. See the
+ <a href="site:w_resource">Resource Class</a> documentation included with Apache WSRF.
+ </note>
+ <section>
+ <title>ManagementEvent notifications</title>
+ <p> WSDM defines a specific event format that is different than a standard WSN notification. Whenever you subscribe to a MUWS related topic, the notifications
+ are always returned in the WSDM event format. The term ManagementEvent notification is used since <code>ManagementEvent</code> is the root element of the
+ notification.
+ </p>
+ <p>A ManagementEvent notification provides a set of standard fields that provide metadata about the event as well as the actual notification element (e.g, a resource
+ property changed event for a resource property). The Metadata includes: report time, event ID, source component, reporter component, as well as an "any" wild card.
+ It is suggested that your custom topics also use this event format. Although, it is not required. Apache Muse provides some helper classes that can be used to create
+ ManagementEvent-based notifications. The instructions are discussed below.
+ </p>
+ </section>
+ </section>
+ <section id="act">
+ <title>Adding Capability Topics</title>
+ <p>A capability topic is created for each MUWS property that is defined in your WSDL. To add MUWS capability topics for these properties, implement the
+ <code>init()</code> of your resource class using the following instructions. The example is taken from
+ the filesystem example. For simplicity, only the <code>OperationalStatus</code> topic is shown.</p>
+ <ol>
+ <li>Create a MUWS topic space.
+ <source>
+org.apache.ws.notification.topics.TopicSpace muwsTopicSpace = new org.apache.ws.notification.topics.impl.TopicSpaceImpl(
+ org.apache.ws.muws.v1_0.MuwsConstants.NSURI_MUWS_PART2_TOPICS );
+getTopicSpaceSet().addTopicSpace( muwsTopicSpace );
+ </source>
+ </li>
+ <li>For each MUWS capability that your resource supports, add a topic to the resource's topic set in the MUWS topic space. The topic should be of the type
+ <code>org.apache.ws.muws.v1_0.topics.ManagementEventTopic</code>.
+ <source>
+org.apache.ws.muws.v1_0.topics.ManagementEventTopic operationalStatusCapabilityTopic;
+
+operationalStatusCapabilityTopic = new org.apache.ws.muws.v1_0.topics.impl.XmlBeansManagementEventTopicImpl(
+ org.apache.ws.muws.v1_0.capability.OperationalStatusCapability.TOPIC_NAME );
+muwsTopicSpace.addTopic( operationalStatusCapabilityTopic );
+ </source>
+ </li>
+ <li>Initialize the resource property to be associated with the topic
+ <source>
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart1.ManageabilityCapabilityDocument operationalStatusCapabilityPropElem =
+ org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart1.ManageabilityCapabilityDocument.Factory.newInstance();
+operationalStatusCapabilityPropElem.setManageabilityCapability( org.apache.ws.muws.v1_0.capability.OperationalStatusCapability.URI );
+resourceProperty.add( operationalStatusCapabilityPropElem );
+ </source>
+ </li>
+ <li>Add the topic as a resource property change listener for the resource property. This will automatically emit ManagementEvent-wrapped resource property change events as they occur.
+ <source>
+resourceProperty = resourcePropertySet.get( FilesystemPropertyQNames.OPERATIONALSTATUS );
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.OperationalStatusDocument statusDoc =
+ org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.OperationalStatusDocument.Factory.newInstance();
+statusDoc.setOperationalStatus( org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.OperationalStatusDocument.OperationalStatus.AVAILABLE );
+resourceProperty.add(statusDoc);
+resourceProperty.setCallback( new example.filesystem.callback.OperationalStatusCallback( m_filesystem ) );
+resourceProperty.addChangeListener( operationalStatusCapabilityTopic );
+ </source>
+ <note>A change listener is not required but can be used if you want management events containing changed property events. The <code>ResourceId</code>
+ property does not require a change listener since the property is read only.</note>
+ </li>
+ </ol>
+ </section>
+ <section>
+ <title>Adding Advertiser Topics</title>
+ <p>The MUWS specification defines an Advertisement capability that provides a notification whenever a manageable resource is created or destroyed. The
+ capability includes four topics, two of which are implemented in Muse:</p>
+ <ul>
+ <li>
+ <code>ManageableResourceCreation</code>
+ </li>
+ <li>
+ <code>ManageableResourceDestruction</code>
+ </li>
+ </ul>
+ <p>Muse implements these topics as part of the <code>ResourceAdvertiser</code> service that is deployed by default in Muse. Therefore, it does not have to be
+ defined in a MUWS WSDL or directly implemented by your WS Resource. See the <a href="site:adv">Using the Resource Advertiser Service</a> section for more
+ information on subscribing to the Advertiser Topics.
+ </p>
+ </section>
+ <section>
+ <title>Adding the Relationship Topics</title>
+ <p>This section discusses five topics that are defined in the MUWS specification to support relationships:</p>
+ <ul>
+ <li>
+ <code>Relationship</code>: A topic for a resource property that notifies a consumer about the relationships that a resource knows about.</li>
+ <li>
+ <code>RelationshipCreated</code>: A topic that notifies a consumer when a new relationship is added.</li>
+ <li>
+ <code>RelationshipDeleted</code>: A topic that notifies a consumer when a relationship is deleted.</li>
+ <li>
+ <code>RelationshipAccessCapability</code>: A topic that notifies a consumer that an interaction with a relationship or its participants has occurred.</li>
+ <li>
+ <code>RelationshipResourceCapability</code>: A topic that notifies a consumer when the identity of a relationship changes. This includes the name, type, and
+ participant properties of a relationship.</li>
+ </ul>
+ <p>The <code>Relationship</code> and <code>RelationshipResourceCapability</code> topics are created in the same manner as discussed in the
+ <a href="#act">Adding Capability Topics</a> above. The <code>Relationship</code> topic represents a property changed event that occurs whenever the list of
+ relationships changes. The <code>RelationshipResourceCapability</code> topic represents property changed events whenever either the name, type, or participants for a
+ relationship changes.
+ </p>
+ <p>The <code>RelationshipCreated</code>, <code>RelationshipDeleted</code>, and <code>RelationshipResourceCapability</code> topics are implemented in Muse by
+ default. Therefore, you only need to add these topics to the topic set in your resource class. For example:</p>
+ <source>
+ try {
+ org.apache.ws.notification.topics.TopicSpace muws2topics = org.apache.ws.muws.MuwsUtils.addRelationshipTopics( getTopicSpaceSet() );
+ } catch ( Exception e ) {
+ throw new RuntimeException( "Failed to add the MUWS RelationshipAdded/Removed topics to the topic set.", e );
+ }
+
+ </source>
+ <p>For more information Relationships, see the <a href="site:rel">Creating Relationships</a> section.</p>
+ </section>
+ <section>
+ <title>Adding Custom Management Events</title>
+ <p>Notifications for custom topics (e.g. my_foo events) can be wrapped as a ManagementEvent notification. While this is not required by the MUWS
+ specification, it may give WSDM notification consumers the ability to process your notification, even if they are unaware of the resource as a managed resource.</p>
+ <p>Muse provides several utility classes that can be used to define a ManagementEvent Topic and wrap a notification. </p>
+
+ <ol>
+ <li>Define a ManagementTopic.
+ <p>Utilizing ManagementEventTopic provides the framework for publishing ManagementEvents.</p>
+ <source>
+ //add/create a TopicSpace for your custom Topics
+ TopicSpace fooTopicSpace = getTopicSpaceSet().addTopicSpace("http://foo/topicspace");
+
+ /**
+ * Provide a Topic name (i.e. FooCapability ) for your new Management Event Topic during creation, this is the
+ * name consumers will use when subscribing to the Topic.
+ */
+ ManagementEventTopic fooCapabilityTopic = new XmlBeansManagementEventTopicImpl("FooCapability");
+
+ //make sure to add the ManagementEventTopic to your defined TopicSpace
+ fooTopicSpace.addTopic(fooCapabilityTopic);
+ </source>
+ </li>
+
+
+ <li>Building a ManagementEvent to publish.
+ <p>In cases where you want to emit an event which is not triggered via a ResourcePropertyValueChangeEvent, you will need to explictly build the ManagementEvent and call publish on the Topic. A custom event is wrapped as a ManagementEvent by adding the custom event XML as a child of the ManagementEventType. Below is an example of adding a custom XmlBean-generated object to a ManagementEventType for a custom notification.</p>
+ <source>
+ //define the situation as per spec
+ Situation situation =
+ new SituationImpl(new CategoryImpl(MuwsConstants.SITUATION_OTHER));
+
+ //build a ManagementEventDocument using the Situation using a helper class
+ XmlBeansManagementEvent xme = new XmlBeansManagementEvent(situation);
+ //extract the XmlBean-generated ManagementEventDocument
+ ManagementEventDocument managementEventDocument = (ManagementEventDocument) ((XmlObjectWrapper) xme).getXmlObject();
+
+ //pull the ManagementEventType from the ManagementEventDocument in order to add your custom event object
+ org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart1.ManagementEventType managementEvent =
+ managementEventDocument.getManagementEvent();
+
+ //add your custom XmlBean-generated object (i.e. fooXmlBeanGeneratedObject) to the ManagementEvent
+ XmlBeanUtils.addChildElement(managementEvent, fooXmlBeanGeneratedObject);
+ </source>
+ </li>
+
+
+ <li>Publishing ManagementNotifications.
+ <p>The use of ManagementEventTopic as the Topic for exposing Notifications provides the ability to publish ManagementEvents. Once you have built the ManagementEvent notification you would like to send, you will need to publish the event to the ManagementTopic.</p>
+ <source>
+ //retrieve the Topic from the Resource
+ ManagementEventTopic fooTopic = (ManagementEventTopic)getTopicSpaceSet().getTopicSpace("http://foo/topicspace").getTopic("FooCapability");
+ try
+ {
+ fooTopic.publish(managementEventDocument);
+ }
+ catch (Exception e)
+ {
+ //handle exception
+ }
+ </source>
+ </li>
+
+ </ol>
+
+
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/relationships.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/relationships.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/relationships.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/relationships.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,134 @@
+<?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 Relationships</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>This section provides instructions for creating relationships among resources. The resources involved in a relationship are called participants. Each participant
+ has a role in the relationship. Resources are related based on their role definitions. Because relationships are specific to a resource management model, no relationship
+ types or roles are defined by MUWS and must be defined by the developer.
+ </p>
+ <p>The examples in this section are taken from the filesystem example. The example demonstrates a simple relationship where a host resource contains a relationship
+ with a filesystem resource. The host resource is considered the <code>container</code> in the relationship and the filesystem resource is considered the
+ <code>containee</code>. The code to define and setup the relationship is added to the <code>init()</code> method of FilesystemResource.java since the FilesystemResource exposes the Relationship resource property.
+ </p>
+ <note>For simplicity, the example relationship is defined within the the filesystem resource. However, relationships do not need to be defined as part of the resource
+ definition. For example, a resource can be created that is not a manageable resource, but does provide the implementation of the relationships for a particular management
+ model.</note>
+ </section>
+ <section>
+ <title>Defining a Relationship</title>
+ <p>To define a relationship, you must create a relationship type and any participant types and then assign each participant a role in the in the relationship:</p>
+ <ol>
+ <li>Create a relationship type.
+ <source>
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.RelationshipType relationshipType = null;
+relationshipType = prop_relationship.addNewRelationship();
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.RelationshipTypeType relationshipTypeType = relationshipType.addNewType();
+org.apache.ws.util.XmlBeanUtils.addChildElement( relationshipTypeType, new javax.xml.namespace.QName( "http://myns.com/", "ContainedBy", "myns" ) );
+ </source>
+ </li>
+ <li>Create participant types and assign each participant a role in this relationship. In this case, two participant types are created.
+ <p><strong>Filesystem Participant Type</strong></p>
+ <source>
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.RelationshipParticipantType relationshipParticipantType = relationshipType.addNewParticipant();
+org.apache.ws.resource.properties.ResourceProperty resourceIdProp = resourcePropertySet.get( FilesystemPropertyQNames.RESOURCEID );
+org.apache.xmlbeans.XmlAnyURI resourceId = (org.apache.xmlbeans.XmlAnyURI) resourceIdProp.get( 0 );
+relationshipParticipantType.setResourceId( resourceId.getStringValue() );
+relationshipParticipantType.setRole( "urn:containee" );
+
+ // NOTE: the below line assumes that the Filesystem resource's EndpointReference field has been initialized
+
+org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType filesystemReference = (org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType) ((org.apache.ws.addressing.XmlBeansEndpointReference)getEndpointReference()).getXmlObject( org.apache.ws.addressing.v2004_08_10.AddressingConstants.NSURI_ADDRESSING_SCHEMA );
+relationshipParticipantType.setManageabilityEndpointReferenceArray( new org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType[] { filesystemReference } );
+ </source>
+ <p><strong>Host Participant Type</strong></p>
+ <source>
+org.oasisOpen.docs.wsdm.x2004.x12.muws.wsdmMuwsPart2.RelationshipParticipantType relationshipParticipantType2 = relationshipType.addNewParticipant();
+org.apache.ws.resource.ResourceHome hostHome = (org.apache.ws.resource.ResourceHome) new javax.naming.InitialContext( ).lookup( HOST_HOME_LOCATION );
+
+// host is a singleton resource w/ a null resource identifier
+
+org.apache.ws.resource.PropertiesResource host = (org.apache.ws.resource.PropertiesResource) hostHome.find( null );
+resourceIdProp = host.getResourcePropertySet().get( org.apache.ws.muws.v1_0.capability.IdentityCapability.PROP_NAME_RESOURCE_ID );
+resourceId = (org.apache.xmlbeans.XmlAnyURI) resourceIdProp.get( 0 );
+relationshipParticipantType2.setResourceId( resourceId.getStringValue() );
+relationshipParticipantType2.setRole( "urn:container" );
+
+// NOTE: the below line assumes that the Host resource's EndpointReference field has been initialized
+
+org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType hostReference = (org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType)
+ ((org.apache.ws.addressing.XmlBeansEndpointReference)host.getEndpointReference()).getXmlObject( org.apache.ws.addressing.v2004_08_
+ 10.AddressingConstants.NSURI_ADDRESSING_SCHEMA );
+relationshipParticipantType.setManageabilityEndpointReferenceArray( new org.xmlsoap.schemas.ws.x2004.x08.addressing.EndpointReferenceType[] { hostReference } );
+ </source>
+ </li>
+ <li>Add properties for the relationship that allow property changed management events
+ <source>
+resourceProperty.add( prop_relationship );
+resourceProperty.addChangeListener( relationshipsCapabilityTopic );
+ </source>
+ <note>See the <a href="site:topics">MUWS-Specific Topics</a> section for more information on relationship topics.</note>
+ </li>
+ </ol>
+ <section>
+ <title>Relationship Fields</title>
+ <p>A relationship is represented by a set of fields. The fields describe the relationship and are returned as part of a relationship notification. The above example
+ implements all the fields that are required. however, the complete list of fields are provided below if you choose to implement them.
+ </p>
+ <ul>
+ <li><code>muws-p2-xs:Name</code>: (optional) A human readable name for a relationship.</li>
+ <li><code>muws-p2-xs:Type</code>: (required) The relationship type to which this relationship belongs.</li>
+ <li><code>muws-p2-xs:Participant</code>: (required) The information about a participant in the relationship. There must be at least two participants, but there may
+ be more than two participants.</li>
+ <li><code>muws-p1-xs:ManageabilityEndpointReference</code>: (optional) A reference to a WSDM manageability endpoint.</li>
+ <li><code>muws-p1-xs:ResourceID</code>: (optional) A WSDM manageable resource identifier which may be reported by the provider of relationship
+ information.</li>
+ <li><code>muws-p2-xs:Role</code>: (required) A URI which identifies the role a participant plays in a relationship. A participant role must be unique within a given
+ instance of the relationship. The set of valid roles is defined by a relationship type.</li>
+ <li><code>muws-p2-xs:Participant/{any}*</code>: (optional) An XML extensibility content which may contain elements that further or otherwise describe a
+ participant.</li>
+ <li><code>muws-p2-xs:AccessEndpoint</code>: (optional) A reference to a Web service endpoint which provides access to this relationship (if available).</li>
+ </ul>
+ </section>
+ </section>
+ <section>
+ <title>Relationship Operations and Properties</title>
+ <p>The MUWS specification defines one relationship operation (<code>QueryRelationshipsByType</code>) and a single resource property (<code>Relationship</code>)
+ that can be used to retrieve relationship information. Both the operation and the resource property must be defined in your MUWS WSDL. If you use the MUWS WSDL
+ template, the operation and property are included, but need to be uncommented.
+ </p>
+ <note>There are also a set of relationship topics that can be used for relationship notifications, see the
+ <a href="site:topics">MUWS-Specific Topics</a> section for more information on relationship topics.</note>
+ <p>The <code>Relationship</code> resource property can be retrieved using the wsrf-rp:GetResourceProperty or wsrf-rp:GetMultipleResourceProperties operations.
+ These operations may be impractical if your management model contains a large number of relationships. As an alternative, the wsrf-rp:QueryResourceProperties operation
+ can be used to retrieve individual relationships by using a query expression. The query expression is a XPath expression. For more information about supporting these
+ operations in your WS Resource, see the <a href="site:w_compose">WSRF WSDL</a> documentation.
+ </p>
+ <p>The <code>QueryRelationshipsByType</code> operation is a quick way to retrieve relationships by a known type. For example, the operation is used in the filesystem
+ example for the relationship type <code>ContainedBy</code>:
+ </p>
+ <source><![CDATA[
+<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:fs="http://ws.apache.org/resource/example/filesystem"
+ xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd">
+
+ <Header xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing">
+ <wsa:To mustUnderstand="1">http://localhost:8080/muse/services/filesystem</wsa:To>
+ <wsa:Action mustUnderstand="1">http://ws.apache.org/resource/example/filesystem/FileSystemPortType/GetResourcePropertyRequest</wsa:Action>
+ <fs:ResourceIdentifier mustUnderstand="1">/dev/vg00/lvol1</fs:ResourceIdentifier>
+ </Header>
+
+ <Body>
+ <muws-p2-xs:QueryRelationshipsByType xmlns:myns="http://myns.com/"><muws-p2-xs:RequestedType>myns:ContainedBy</muws-p2-xs:RequestedType></muws-p2-
+ xs:QueryRelationshipsByType>
+ </Body>
+</Envelope>]]>
+ </source>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,101 @@
+<?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 MUWS WSDL</title>
+ </header>
+ <body>
+ <section>
+ <title>Using the MUWS Template</title>
+ <p>The Web Services Description Language (WSDL) is used to expose resources and notifications as WS-Resources and also includes optional fields, operations, and
+ notifications that may be included in the definition of a resource that allow management applications to manage the resource in a standardized fashion. The WSDL must
+ conform to the conventions as described in the MUWS specification as well as the conventions described in the <a href="ext:spec">WSRF</a> and <a href="ext:wsn">WSN</a>
+ Specifications. To make it easier to write a MUWS WSDL, Muse 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 MUWS-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 MUWS PortType</title>
+ <p>A MUWS WSDL should contain only one portType. The portType aggregates operations from the WSRF, WSN, and MUWS specification-defined portTypes
+ as well as custom resource-specific operations. If you copied the WSDL template file as described above, your WSDL file
+ already contains a MUWS-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>
+ <note>The WSRF portTypes - from WS-ResourceProperties (WSRF-RP) and WS-ResourceLifetime (WSRF-RL)- and their associated operations are described in the Apache
+ WSRF <a href="site:w_compose">WSDL Documentation</a>. The instructions include defining the resource properties document, custom properties, and custom
+ operations. The WSN portTypes - from WS-BaseNotification - and their associated operations are described in the Apache Pubscribe
+ <a href="site:p_compose">WSDL Documentation</a>. The instructions include defining notification producers, notification topics, and notification consumers.
+ </note>
+ <section>
+ <title>MUWS PortTypes</title>
+ <p>The MUWS specification defines eight portTypes. However, only the <code>Relationships</code> portType contains an operation that can be added to the portType of your
+ WSDL. The other portTypes are used to organize and expose resource properties and need to be defined in the <code>type</code> section of a WSDL as you would
+ any other resource property. Among these properties, the ResourceID property is required and must be included in a MUWS compliant WSDL.
+ </p>
+ <table>
+ <tr>
+ <th>PortType</th>
+ <th>Operations</th>
+ <th>Properties</th>
+ </tr>
+ <tr>
+ <td>Identity</td>
+ <td/>
+ <td>ResourceId</td>
+ </tr>
+ <tr>
+ <td>ManageabilityCharacteristics</td>
+ <td/>
+ <td>ManageabilityCapability</td>
+ </tr>
+ <tr>
+ <td>CorrelatableProperties</td>
+ <td/>
+ <td>CorrelatableProperties</td>
+ </tr>
+ <tr>
+ <td>Description</td>
+ <td/>
+ <td>Caption, Description, Version</td>
+ </tr>
+ <tr>
+ <td>OperationalStatus</td>
+ <td/>
+ <td>OperationalStatus</td>
+ </tr>
+ <tr>
+ <td>Metrics</td>
+ <td/>
+ <td>CurrentTime</td>
+ </tr>
+ <tr>
+ <td>Relationships</td>
+ <td>QueryRelationshipsByType</td>
+ <td>Relationship</td>
+ </tr>
+ <tr>
+ <td>RelationshipResource</td>
+ <td/>
+ <td>Name, Type, Participant</td>
+ </tr>
+ </table>
+ </section>
+ <section>
+ <title>Metadata Operations</title>
+ <p>The template contains two operations that are not defined by the WSRF, WSN or WSDM 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:w_metadata">Adding Service Metadata</a> section of the Apache
+ WSRF documentation.</p>
+ </section>
+ </section>
+ </body>
+</document>
Added: webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl_tool.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl_tool.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl_tool.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/dev_guide/wsdl_tool.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,144 @@
+<?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 MUWS WS Resource. The artifiacts include:</p>
+ <ul>
+ <li>A set of Java classes based on the WSDL definition. This includes a service, resource, and
+ home class. Some of the Java code will need to be manually edited after the files are generated.</li>
+ <li>Interfaces for custom operations.</li>
+ <li>Java bindings for all Types that are defined in the WSDL. The interfaces and classes are
+ 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 MUWS 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.muws.tool.MuwsWsdl2JavaTask</code>) which extends the
+ Apache Pubscribe Ant task (<code>org.apache.ws.notification.tool.WsnWsdl2JavaTask</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>muse.webapp.dir</code> property and set it to the location where the Muse 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 MUWS 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="MuwsWsdl2JavaTask"
+ classname="org.apache.ws.muws.tool.MuwsWsdl2JavaTask"
+ classpath="path/to/muse.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 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 directory
+ named <code>/generated</code>. To simplify the example, the classpath is referenced. You must set the <code>${muse.home}</code> Ant property to <code>
+ INSTALL_DIR</code> (e.g. /opt/muse-1.0beta).</p>
+ <source><![CDATA[
+
+ <property name="muse.webapp.dir" location="${muse.home}/webapps/muse" />
+ <path id="muse.classpath.id">
+ <pathelement location="${muse.webapp.dir}/WEB-INF/classes" />
+ <fileset dir="${muse.webapp.dir}/WEB-INF/lib" includes="*.jar" />
+ </path>
+
+ <taskdef name="wsdl2Java" classname="org.apache.ws.muws.tool.MuwsWsdl2JavaTask" classpath="muse.classpath.id" />
+
+ <wsdl2Java wsdl="path/to/your.wsdl"
+ outputdir="generated"
+ classpath="muse.classpath.id" />]]></source>
+ <p>If you want to generate the files for multiple WSDLs, you can use:</p>
+ <source><![CDATA[
+
+ <wsdl2Java outputdir="generated" classpath="muse.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/muse/getting_started.xml
URL: http://svn.apache.org/viewvc/webservices/muse/branches/1.0/src/site/content/xdocs/muse/getting_started.xml?rev=411217&view=auto
==============================================================================
--- webservices/muse/branches/1.0/src/site/content/xdocs/muse/getting_started.xml (added)
+++ webservices/muse/branches/1.0/src/site/content/xdocs/muse/getting_started.xml Fri Jun 2 10:30:32 2006
@@ -0,0 +1,131 @@
+<?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 Muse</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>The topics in this section detail how to install Apache Muse 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 Muse. It highlights the most common procedures that are used to create and deploy MUWS-compliant Web
+ services for resources.
+ </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 Muse. 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 Muse 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 WSDM specifications.</p>
+ <p>To run and install Apache Muse, 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 Muse:</p>
+ <ol>
+ <li>Download the Apache Muse <a href="site:releases">binary distribution</a>.</li>
+ <li>Unzip the 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/muse</code> directory to <code>TOMCAT_HOME/webapps</code>.</li>
+ <li>Start Tomcat.</li>
+ <li>Using a browser, go to <a href="http://localhost:8080/muse">http://localhost:8080/muse</a>. The Apache Muse welcome page
+ displays.</li>
+ <li>From the Apache-Axis page, click <a href="http://localhost:8080/muse/services">View</a>. The list of deployed Web services
+ displays. Four services are deployed: <code>SubscriptionManager</code>, <code>ResourceAdvertiser</code>,
+ <code>AdminService</code>, and <code>Version</code>. The <code>AdminService</code> and <code>Version</code> services are default
+ Apache-Axis services. The <code>SubscriptionManager</code> is used to pause, resume, destroy, or update
+ subscriptions. Lastly, <code>ResourceAdvertiser</code> is used to subscribe to notifications about resources which are created and destroyed.</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 Muse. The demo uses an example that is
+ included in the distribution. The example represents a UNIX file system resource whose
+ management capabilities are exposed as a MUWS-compliant Web service. In addition, a host resource is also provided to demonstrate relationships between resources.
+ </p>
+ <note>The <a href="site:tut">tutorial</a> provides a step-by-step approach for exposing the management capabilities of the filesystem and host resources. 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>muse.webapp.dir</code> property and set it to the location where the Muse 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>Using a text editor, open <code>TOMCAT_HOME/webapps/muse/WEB-INF/classes/jndi-config.xml</code>.</li>
+ <li>From the <code><![CDATA[<service name="host">]]></code> block, remove the <code>resourceIdentifierReferenceParameterName</code>
+ parameter. This parameter is not required since the host service is a singleton. Removing this entry ensures that Muse does not look for a resource id
+ in the WS Address headers.</li>
+ <li>Save and close jndi-config.xml.</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/muse/services">
+ http://localhost:8080/muse/services</a> and verify that the filesystem service is deployed.
+ </li>
+ <li>From a command prompt change directories to <code>INSTALL_DIR/examples/filesystem</code> directory. An ANT-based SOAP client that is included in
+ the distribution is used to send a SOAP request to the filesystem Web service.</li>
+ <li>
+ <strong>Subscribe to a MUWS Notification Topic: </strong>
+ <br/>
+ <p>In this step, a request is sent to subscribe to the MUWS notification topic for the <code>OperationalStatus</code> resource property. </p>
+ <source><![CDATA[
+ ant -f soapclient.xml -Durl=http://localhost:8080/muse/services/filesystem -Dxml=requests/Subscribe_op_status.soap]]></source>
+ <note>To complete step 16 later in this demonstration, you must copy the <code>ResourceIdentifier</code> value that is returned in the SOAP body of
+ the response for this request. This is the subscription's identifier.
+ </note>
+ <br/>
+ </li>
+ <li>
+ <strong>Cause an Event:</strong>
+ <br/>
+ <p>In this step, the <code>Unmount</code> operation is called causing the <code>OperationalStatus</code> resource property to change. This will cause
+ an <code>OperationalStatus</code> notification to be published.</p>
+ <source><![CDATA[
+ ant -f soapclient.xml -Durl=http://localhost:8080/muse/services/filesystem -Dxml=requests/unmount.soap]]></source>
+ </li>
+ <li>
+ <strong>View Notification: </strong>
+ <br/>
+ <p>In this step, we retrieve the <code>OperationalStatus</code> notification that was published when the <code>OperationalStatus</code> resource property
+ was changed in the previous step. The notification indicates that the <code>OperationalStatus</code> has changed from
+ <code>available</code> to <code>unavailable</code>.</p>
+ <source><![CDATA[
+ ant -f soapclient.xml -Durl=http://localhost:8080/muse/services/filesystem -Dxml=requests/GetCurrentMessage.soap]]></source>
+ </li>
+ <li>
+ <strong>Destroy Subscription:</strong>
+ <br/>
+ <p>In this step, a request is sent via the SubscriptionManager service to destroy the <code>OperationalStatus</code> notification topic subscription.
+ Before completing this step, open the <code>requests/Destroy_Subscription.soap</code> file and update the <code>sub:ResourceIdentifier</code> element
+ with the value that was copied in step 13. Save and close the file.</p>
+ <source><![CDATA[
+ ant -f soapclient.xml -Durl=http://localhost:8080/muse/services/SubscriptionManager -Dxml=requests/Destroy_Subscription.soap]]></source>
+ </li>
+ <li>
+ <strong>View Relationships</strong>
+ <br/>
+ <p>In this step, a request is sent to retrieve all relationships of the type <code>ContainedBy</code>. The filesystem resource has a <code>ContainedBy</code>
+ relationship with the host resource. The response indicates the participants of the relationship and the role each participant plays in the relationship.</p>
+ <source><![CDATA[
+ ant -f soapclient.xml -Durl=http://localhost:8080/muse/services/filesystem -Dxml=requests/QueryRelationshipsByType.soap]]></source>
+ </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