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 wi...@apache.org on 2005/09/29 23:01:24 UTC
svn commit: r292547 - /webservices/muse/trunk/client/bin/README.txt
Author: wire
Date: Thu Sep 29 14:01:23 2005
New Revision: 292547
URL: http://svn.apache.org/viewcvs?rev=292547&view=rev
Log:
Updated docs
Modified:
webservices/muse/trunk/client/bin/README.txt
Modified: webservices/muse/trunk/client/bin/README.txt
URL: http://svn.apache.org/viewcvs/webservices/muse/trunk/client/bin/README.txt?rev=292547&r1=292546&r2=292547&view=diff
==============================================================================
--- webservices/muse/trunk/client/bin/README.txt (original)
+++ webservices/muse/trunk/client/bin/README.txt Thu Sep 29 14:01:23 2005
@@ -21,4 +21,315 @@
For instructions on how to use the product, please
refer to the following URL.
- http://kolvir.esr.hp.com:8081/JSPWiki/Wiki.jsp?page=MuseClient
\ No newline at end of file
+ http://kolvir.esr.hp.com:8081/JSPWiki/Wiki.jsp?page=MuseClient
+
+A copy of this site is listed below.
+-----------------------------------------------
+ Muse Client Documentation
+This page contains the evolving documentation for the Muse Client that will be contributed to the Apache Foundation as a comapnion piece to the Muse server toolkit which implements the MUWS specification.
+
+Table of Contents
+
+ * Introduction
+ * Obtaining the Client
+ * Command Line Tool
+ * How do I get or set a resource property value in java?
+ * How do I listen for property change events in java?
+
+MuseIntroduction
+
+Search Wiki:
+Your trail: Main | PageIndex | MuseClient
+
+The Muse client library is indended to work in conjunction with a Java servlet engine which has an instance of Apache Axis deployed on it. Deployed within the Apache Axis servlet should be a WSDM managed resource which takes the form of a web service endpoint.
+
+The development of one of these endpoints will be left to the Muse documentation. If you need a managed resource to experiment with you can download a pre-configured install of tomcat which contains our unit test managed resource in a ready to run format. This can be downloaded here.
+
+Once you have downloaded and extracted this archive, execute the run.bat file in the root of the directory you have created. This will expose the following managed resource EPR which you can use to experiment with:
+
+http://localhost:8080/muse/epr/demo-epr.xml
+
+This EPR exposes the following QNames for properties:
+
+ * {http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd}LastResponseTime
+ * {http://ws.apache.org/service/testresource}TestMetric
+ * {http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd}ManageabilityCapability
+ * {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd}TopicExpressionDialects
+ * {http://ws.apache.org/service/testresource}Price
+ * {http://ws.apache.org/service/testresource}Name
+ * {http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd}ResourceId
+ * {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd}FixedTopicSet
+ * {http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd}OperationalStatus
+ * {http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd}CurrentTime
+ * {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd}Topic
+
+ Obtaining the client
+
+Unfortunatly, you must build your own binary of the client until it become included inside muse itself.
+
+To build the current release you must.
+
+Install Subversion http://subversion.tigris.org/project_packages.html.
+
+or
+
+Use Totrise SVN: http://tortoisesvn.tigris.org/
+
+Use one of these tools to check out:
+
+http://svn.apache.org/repos/asf/webservices/muse/trunk/src/examples/client
+
+Once this checkout completes install maven
+
+http://maven.apache.org/start/download.html
+
+Put maven on your PATH.
+
+Using a command line, run the following command in the project root directory.
+
+maven dist
+
+This will cause the client to be built.
+
+We apologize for requiring you to build your own copy of the client but it is neccesary until the client becomes a part of an offical muse relese. HP is consuming what is an Apache open source product, not and internal HP product and it must be obtained directly from apache. All issues must be reported via Apache defect tracking methods. Issues can be filed at http://nagoya.apache.org/jira/browse/Muse.
+
+If you have any support questions about this product, please send them to the Apache Muse mailing list at muse-dev.at.ws.apache.org.
+
+ Muse Client Command Line Tool
+
+The Muse Client comes with a simple command line tool for resource testing. As of now the tool can be used to:
+
+ * Get a list of all available properties and their values. Note that is will only work if your resource supports QueryResourceProperties. This is an optional operation in the MUWS 1.0 spec.
+ o Example: client http://localhost:8080/muse/epr/demo-epr.xml dump
+ * Get the value of a single property by QName
+ o Example: client http://localhost:8080/muse/epr/demo-epr.xml get {http://ws.apache.org/service/testresource}TestMetric
+ * Set the value of an property. Note that this will only work if your resource supports the optional operation SetResourceProperties.
+ o Example: client http://localhost:8080/muse/epr/demo-epr.xml set {http://ws.apache.org/service/testresource}TestMetric 80.0
+
+In our next release the command line tool will support a listener configuration as well. This will allow you to start an instance of the tool to subscribe to a resource and act as a Notification Consumer. Another instance of the tool would then be used to make a change to a property to trigger a notification.
+
+Getting and Setting Resource Property Values In Java
+
+The class below can get the value of a property and set set it as well. Note that the resource must support the operation SetResourceProperties for setting to work. Also note that this example uses a utility method, getPropertyAsString which assumes that the property will be returning an xsi:string primative value. If you are dealing with a complex property value you will be required to construct your own XML Object which is beyond the scope of this simple example.
+
+import java.net.MalformedURLException;
+import java.net.URL;
+
+import javax.xml.namespace.QName;
+
+import org.apache.ws.client.muse.client.ManageableResource;
+import org.apache.ws.client.muse.client.model.SetPropertiesRequest;
+
+public class Sample {
+ QName NAME = new QName( "http://ws.apache.org/service/testresource", "Name", "tns");
+ URL eprURL;
+
+ public Sample() {
+ super();
+ try {
+ eprURL=new URL("http://localhost:8080/muse/epr/demo-epr.xml");
+ } catch (MalformedURLException e) {
+ e.printStackTrace();
+ }
+ }
+ public String getNameOfResource() throws Exception{
+ URL eprURL=new URL("http://localhost:8080/muse/epr/demo-epr.xml");
+ ManageableResource managedResource = ManageableResource.Factory.create(null, eprURL);
+ String propValue=managedResource.getPropertyAsString(NAME);
+ return propValue;
+ }
+
+ public void setNameOfResource() throws Exception{
+ ManageableResource managedResource = ManageableResource.Factory.create(null, eprURL);
+ SetPropertiesRequest spr=SetPropertiesRequest.Factory.create();
+ spr.addUpdateRequest(NAME,new String[]{"New Name"});
+ managedResource.setProperties(spr);
+ }
+
+}
+
+ Listening for Event Notifications
+
+If your particular property can send notifications when it changes then it will publish a topic under the following property QName.
+
+ * {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd}Topic
+
+You will need to select one of the returned QNames as a topic to receive notifications on.
+
+Below is some sample output showing the results of the command line command: client http://localhost:8080/muse/epr/demo-epr.xml get {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd}To pic
+
+<------------------------------------>
+Name: {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-
+01.xsd}Topic
+Value: <wsn:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpressio
+n/Simple" xmlns:wsdm="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-par
+t2-events.xml" xmlns:wsn="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNoti
+fication-1.2-draft-01.xsd" xmlns:wsrf="http://docs.oasis-open.org/wsrf/2004/06/w
+srf-WS-ResourceProperties-1.2-draft-01.xsd" xmlns:soapenv="http://schemas.xmlsoa
+p.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="ht
+tp://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://schemas.xmlsoap.org/w
+s/2004/08/addressing">wsdm:OperationalStatusCapability</wsn:Topic>
+<------------------------------------>
+Name: {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-
+01.xsd}Topic
+Value: <wsn:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpressio
+n/Simple" xmlns:wsdm="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-par
+t2-events.xml" xmlns:wsn="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNoti
+fication-1.2-draft-01.xsd" xmlns:wsrf="http://docs.oasis-open.org/wsrf/2004/06/w
+srf-WS-ResourceProperties-1.2-draft-01.xsd" xmlns:soapenv="http://schemas.xmlsoa
+p.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="ht
+tp://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://schemas.xmlsoap.org/w
+s/2004/08/addressing">wsdm:IdentityCapability</wsn:Topic>
+<------------------------------------>
+Name: {http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-
+01.xsd}Topic
+Value: <wsn:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpressio
+n/Simple" xmlns:wsdm="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-par
+t2-events.xml" xmlns:wsn="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNoti
+fication-1.2-draft-01.xsd" xmlns:wsrf="http://docs.oasis-open.org/wsrf/2004/06/w
+srf-WS-ResourceProperties-1.2-draft-01.xsd" xmlns:soapenv="http://schemas.xmlsoa
+p.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="ht
+tp://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://schemas.xmlsoap.org/w
+s/2004/08/addressing">wsdm:TestMetricMonitorChannel</wsn:Topic>
+
+Lets say we want to receive notifications from the wsdm:TestMetricMonitorChannel.
+
+The source sample below contains examples of how to create a listner and request notifications.
+
+import java.io.IOException;
+import java.net.MalformedURLException;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.net.UnknownHostException;
+import java.util.Observable;
+import java.util.Observer;
+
+import javax.xml.namespace.QName;
+
+import org.apache.ws.addressing.EndpointReference;
+import org.apache.ws.client.muse.client.ManageableResource;
+import org.apache.ws.client.muse.client.NotificationConsumer;
+import org.apache.ws.client.muse.client.impl.exceptions.FaultException;
+import org.apache.ws.client.muse.client.impl.exceptions.UnexpectedServerResponseException;
+import org.apache.ws.client.muse.client.model.ChangeNotification;
+import org.apache.ws.client.muse.client.model.Notification;
+import org.apache.ws.client.muse.client.model.Situation;
+import org.apache.ws.client.muse.client.model.TopicExpression;
+import org.apache.xmlbeans.XmlException;
+
+public class Sample2 implements Observer {
+
+ private static final int LISTENER_TIMEOUT = 30000;
+
+ private static final int LISTERNER_PORT = 8888;
+
+ private NotificationConsumer listner;
+
+ private URL eprURL;
+
+ private ManageableResource subscription;
+
+ public Sample2() {
+ super();
+ try {
+ eprURL = new URL("http://localhost:8080/muse/epr/demo-epr.xml");
+ } catch (MalformedURLException e) {
+ e.printStackTrace();
+ }
+
+ }
+
+ /**
+ * This operation causes an HTTP listener to be created port 8888.
+ * NotificationConsumer implements the observer pattern. Anyone who wants to
+ * receive the notification must add themselves as an obverver.
+ *
+ * @throws IOException
+ */
+ public void createNotificationListener() throws IOException {
+ this.listner = NotificationConsumer.Factory.create(null,
+ LISTERNER_PORT, LISTENER_TIMEOUT);
+ this.listner.addObserver(this);
+ this.listner.start();
+ }
+
+ /**
+ * This operation causes notification to be sent back to us whenever the
+ * TestMetric value is changed.
+ *
+ * @throws MalformedURLException
+ * @throws XmlException
+ * @throws IOException
+ * @throws URISyntaxException
+ * @throws UnexpectedServerResponseException
+ * @throws FaultException
+ */
+ public void subscribe() throws MalformedURLException, XmlException,
+ IOException, URISyntaxException, UnexpectedServerResponseException,
+ FaultException {
+ ManageableResource resource = ManageableResource.Factory.create(null,
+ eprURL);
+ QName topicName = new QName(
+ "http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml",
+ "TestMetricMonitorChannel");
+ TopicExpression topic = TopicExpression.Factory.create(null, topicName);
+ this.subscription = resource.subscribe(topic, listner
+ .getEndpointReference());
+ }
+
+ /**
+ * It is not always clear to the developer that the Subscribe operation
+ * returns a Subscription amanged resource. Destroying this resource
+ * terminates the subscription.
+ *
+ * @throws URISyntaxException
+ * @throws IOException
+ * @throws XmlException
+ * @throws UnexpectedServerResponseException
+ * @throws FaultException
+ */
+ public void unsubscribe() throws URISyntaxException, IOException,
+ XmlException, UnexpectedServerResponseException, FaultException {
+ this.subscription.destroy();
+ }
+
+ /**
+ * When you want to stop the listener, you should first unregister yourself
+ * as an observer. Stopping the lisnter will cauase it to shut down. It may
+ * be restarted again by calling start.
+ *
+ */
+ public void destroyNotificationListener() {
+ this.listner.deleteObserver(this);
+ this.listner.stop();
+ }
+
+ /**
+ * Notification's Arrive here.
+ */
+ public void update(Observable notificationListnerObservable,
+ Object notificationObject) {
+ NotificationConsumer notificationListener = (NotificationConsumer) notificationListnerObservable;
+
+ // What Consumer sent this message?
+ EndpointReference listenerEpr = null;
+ try {
+ listenerEpr = notificationListener.getEndpointReference();
+ } catch (UnknownHostException e) {
+ e.printStackTrace();
+ }
+
+ // What is the content of the Change Notification?
+ Notification notification = (Notification) notificationObject;
+ ChangeNotification changeNotification = notification
+ .getChangeNotification();
+
+ // What is the situation?
+ Situation situation = notification.getSituation();
+
+ // What is the raw text of the notification?
+ String text = notification.getNotificationMessage().toString();
+ }
+
+}
+