edu.indiana.extreme.lead.resource_catalog.client.util
Class ServiceCatalogUtil

java.lang.Object
  extended by edu.indiana.extreme.lead.resource_catalog.client.util.ServiceCatalogUtil

public class ServiceCatalogUtil
extends java.lang.Object

Utility for a client to invoke methods in the resource catalog to manage workflow and web-service related entries. The resource catalog stores 3 types of documents related to registered web-services: the Service Map (SM), the Abstract WSDL (AWSDL) and the Concrete WSDL (CWSDL).

The resource catalog service uses an XML database to store the SM, AWSDL, and CWSDL documents. It provides wrapper APIs for standard functions such as adding, removing, and querying for these documents using their QNames. It also provides an XQuery API for performing more complex queries. The catalog stores these 3 types of documents in 3 separate collections within the XML database. These collections can be refered to in the XQuery using the special strings $SM_COLLECTION, $AWSDL_COLLECTION, and $CWSDL_COLLECTION respectively for the SM, AWSDL, and CWSDL documents.

The resource catalog supports lifetime management of the CWSDL documents stored in it. Every CWSDL document registered in the catalog requests a lifetime for the document. If the requested lifetime is outside the catalog's bounds, it assigns a lifetime greater than or less than the requested lifetime and returns this with the call to register the CWSDL. The client is responsible for renewing this lifetime of the CWSDL while the service is valid. Once the lifetime of the CWSDL expires, the resource catalog is free to delete this CWSDL when it next runs its garbage collector. The renewal should be done a couple of minutes before the assigned lifetime expires to account for transport and processing time. Note that the lifetime calculation is free from clock skew or timezones since it is always calculated with relative to the current time.

Version:
$Revision: 1.5 $
Author:
Yogesh L. Simmhan [mailto:ysimmhan@cs.indiana.edu]

Nested Class Summary
static class ServiceCatalogUtil.CollectionHolder
           
 
Field Summary
static java.lang.String RESCAT_NS
           
static java.lang.String WSDL_NS
           
 
Constructor Summary
ServiceCatalogUtil()
           
 
Method Summary
static java.lang.String getAbstractWsdl(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method getAbstractWsdl.
static java.lang.String getAppDesc(ResourceCatalogPortType stub, javax.xml.namespace.QName appName, java.lang.String hostName)
          Method getAppDesc.
static java.lang.String getConcreteWsdl(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method getGetConcreteWsdl.
static java.lang.String[] getConcreteWsdlByAbstractWsdlQName(ResourceCatalogPortType stub, javax.xml.namespace.QName awsdlQName)
          Method getConcreteWsdlByAbstractWsdlQName.
static java.lang.String getHostDesc(ResourceCatalogPortType stub, java.lang.String hostName)
          Method getHostDesc.
static java.lang.String getServiceMap(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method getServiceMap.
static WsdlSummaryDocument.WsdlSummary[] listAbstractWsdls(ResourceCatalogPortType stub)
          Method listAbstractWsdls.
static java.lang.String[] performXQuery(ResourceCatalogPortType stub, java.lang.String xquery)
          Method performXQuery.
static void registerAbstractWsdl(ResourceCatalogPortType stub, java.lang.String awsdlStr)
          Method registerAbstractWsdl.
static void registerAppDesc(ResourceCatalogPortType stub, java.lang.String appDescStr)
          Method registerAppDesc.
static long registerConcreteWsdl(ResourceCatalogPortType stub, java.lang.String cwsdlStr, long lifetimeMins)
          Method registerConcreteWsdl.
static void registerHostDesc(ResourceCatalogPortType stub, java.lang.String hostDescStr)
          Method registerHostDesc.
static void registerServiceMap(ResourceCatalogPortType stub, java.lang.String smStr, java.lang.String awsdlStr)
          Method registerServiceMap.
static void removeAbstractWsdl(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method removeAbstractWsdl.
static void removeAppDesc(ResourceCatalogPortType stub, javax.xml.namespace.QName appName, java.lang.String hostName)
          Method removeAppDesc.
static void removeConcreteWsdl(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method removeConcreteWsdl.
static void removeConcreteWsdlByAbstractWsdlQName(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method removeConcreteWsdlByAbstractWsdlQName.
static void removeHostDesc(ResourceCatalogPortType stub, java.lang.String hostName)
          Method removeHostDesc.
static void removeServiceMap(ResourceCatalogPortType stub, javax.xml.namespace.QName query)
          Method removeServiceMap.
static long renewConcreteWsdl(ResourceCatalogPortType stub, javax.xml.namespace.QName query, long lifetimeMins)
          Method renewConcreteWsdl.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WSDL_NS

public static final java.lang.String WSDL_NS
See Also:
Constant Field Values

RESCAT_NS

public static final java.lang.String RESCAT_NS
See Also:
Constant Field Values
Constructor Detail

ServiceCatalogUtil

public ServiceCatalogUtil()
Method Detail

registerServiceMap

public static void registerServiceMap(ResourceCatalogPortType stub,
                                      java.lang.String smStr,
                                      java.lang.String awsdlStr)
Method registerServiceMap. Registers a SM document along with its AWSDL with the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
smStr - a ServiceMap doc as String
awsdlStr - a AWSDL document as String

getServiceMap

public static java.lang.String getServiceMap(ResourceCatalogPortType stub,
                                             javax.xml.namespace.QName query)
Method getServiceMap. Retrieves a SM doc identified by its unique QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a the QName uniquely identifying a SM doc. This is given by the namespace /ServiceMap/service/serviceName/@targetNamespace and local name /ServiceMap/service/serviceName
Returns:
a String representing a SM XML doc. Null or empty string if not present.

removeServiceMap

public static void removeServiceMap(ResourceCatalogPortType stub,
                                    javax.xml.namespace.QName query)
Method removeServiceMap. Deletes a SM doc identified by its unique QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a the QName uniquely identifying a SM doc. This is given by the namespace /ServiceMap/service/serviceName/@targetNamespace and local name /ServiceMap/service/serviceName

registerHostDesc

public static void registerHostDesc(ResourceCatalogPortType stub,
                                    java.lang.String hostDescStr)
Method registerHostDesc. Registers a HOst Description document with the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
hostDescStr - a HostDescription XML document as a string

getHostDesc

public static java.lang.String getHostDesc(ResourceCatalogPortType stub,
                                           java.lang.String hostName)
Method getHostDesc. Retrieves a host description doc identified by its unique hostname

Parameters:
stub - a wrapper to a ResourceCatalog webservice
hostName - the hostname that uniquely identifies the hostDecs doc. This is the /HostDescription/hostName element in the HostDesc doc.
Returns:
a String representing a HostDesc XML doc. Null or empty string if not present.

removeHostDesc

public static void removeHostDesc(ResourceCatalogPortType stub,
                                  java.lang.String hostName)
Method removeHostDesc. Deletes a hostDesc doc identified by its unique hostname

Parameters:
stub - a wrapper to a ResourceCatalog webservice
hostName - the hostname that uniquely identifies the hostDecs doc. This is the /HostDescription/hostName element in the HostDesc doc.

registerAppDesc

public static void registerAppDesc(ResourceCatalogPortType stub,
                                   java.lang.String appDescStr)
Method registerAppDesc. Registers a Application Description document with the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
appDescStr - a ApplicationDescription XML document as a string

getAppDesc

public static java.lang.String getAppDesc(ResourceCatalogPortType stub,
                                          javax.xml.namespace.QName appName,
                                          java.lang.String hostName)
Method getAppDesc. Retrieves a application description doc unique identified by its appQName and hostname

Parameters:
stub - a wrapper to a ResourceCatalog webservice
appName - the appName that partly identifies the appDesc doc. This is the {/ApplicationDescription/applicationName/@targetNamespace}/ApplicationDescription/applicationName element in the AppDesc doc.
hostName - the hostname that partly identifies the appDesc doc. This is the /ApplicationDescription/deploymentDescription/hostName element in the AppDesc doc.
Returns:
a String representing an AppDesc XML doc. Null or empty string if not present.

removeAppDesc

public static void removeAppDesc(ResourceCatalogPortType stub,
                                 javax.xml.namespace.QName appName,
                                 java.lang.String hostName)
Method removeAppDesc. Deletes a appDesc doc unique identified by its appQName and hostname

Parameters:
stub - a wrapper to a ResourceCatalog webservice
appName - the appName that partly identifies the appDesc doc. This is the {/ApplicationDescription/applicationName/@targetNamespace}/ApplicationDescription/applicationName element in the AppDesc doc.
hostName - the hostname that partly identifies the appDesc doc. This is the /ApplicationDescription/deploymentDescription/hostName element in the AppDesc doc.

registerAbstractWsdl

public static void registerAbstractWsdl(ResourceCatalogPortType stub,
                                        java.lang.String awsdlStr)
Method registerAbstractWsdl. Registers a AWSDL document with the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
awsdlStr - a String containg the AWSDL XML doc.

getAbstractWsdl

public static java.lang.String getAbstractWsdl(ResourceCatalogPortType stub,
                                               javax.xml.namespace.QName query)
Method getAbstractWsdl. Returns the AWSDL doc identified by its unique QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a AWSDL doc. This is given by the namespace /definitions/@targetNamespace and local name /definitions/@name
Returns:
a String representing the AWSDL XML doc. Null or empty string if not present.

listAbstractWsdls

public static WsdlSummaryDocument.WsdlSummary[] listAbstractWsdls(ResourceCatalogPortType stub)
Method listAbstractWsdls. This returns a summary of all AWSDLs present in the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
Returns:
a WsdlSummary array, each item in which corresponds to a AWSDL doc present in the resource catalog. A WsdlSummary contains the essential documentation present in the AWSDL, such as its QName, description, and portTypes present. This QName can be used to perform other queries such as getting related SMs or CWSDLs.

removeAbstractWsdl

public static void removeAbstractWsdl(ResourceCatalogPortType stub,
                                      javax.xml.namespace.QName query)
Method removeAbstractWsdl. Deletes a AWSDL from the resource catalog uniquely identified by its QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a AWSDL doc. This is given by the namespace /definitions/@targetNamespace and local name /definitions/@name

registerConcreteWsdl

public static long registerConcreteWsdl(ResourceCatalogPortType stub,
                                        java.lang.String cwsdlStr,
                                        long lifetimeMins)
Method registerConcreteWsdl. Registers a CWSDL document with the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
cwsdlStr - a String representing the CWSL Xml doc
lifetimeMins - the lifetime (in minutes from current time) requested for the cwsdl document. The actual lifetime assigned is returned. Unless renewed, after the expiration of this assigned lifetime, the cwsdl document will be deleted when the next garbage collection run takes place in the resource catalog.
Returns:
the assigned lifetime for the cwsdl document: number of minutes from current time that the cwsdl is considered to be expired unless renewed

renewConcreteWsdl

public static long renewConcreteWsdl(ResourceCatalogPortType stub,
                                     javax.xml.namespace.QName query,
                                     long lifetimeMins)
Method renewConcreteWsdl. Renews the lifetime of a CWSDL document present in the resource catalog.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a CWSDL doc. This is given by the namespace /definitions/@targetNamespace and local name /definitions/@name
lifetimeMins - the lifetime (in minutes from current time) requested for the cwsdl document. The actual lifetime assigned is returned. Unless renewed again, after the expiration of this assigned lifetime, the cwsdl document will be deleted when the next garbage collection run takes place in the resource catalog.
Returns:
the assigned lifetime for the cwsdl document: number of minutes from current time that the cwsdl is considered to be expired unless renewed. -1 if no QName matched the given QName.

getConcreteWsdl

public static java.lang.String getConcreteWsdl(ResourceCatalogPortType stub,
                                               javax.xml.namespace.QName query)
Method getGetConcreteWsdl. Returns the CWSDL doc identified by its unique QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a CWSDL doc. This is given by the namespace /definitions/@targetNamespace and local name /definitions/@name
Returns:
a String representing the CWSDL XML doc. Null or empty string if not present.

getConcreteWsdlByAbstractWsdlQName

public static java.lang.String[] getConcreteWsdlByAbstractWsdlQName(ResourceCatalogPortType stub,
                                                                    javax.xml.namespace.QName awsdlQName)
Method getConcreteWsdlByAbstractWsdlQName. Returns the CWSDL documents which have a common AWSDL given by the unique QName for the AWSDL.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a AWSDL doc whose CWSDLs need to be returned. This is QName is matched in the CWSDLs with the namespace in /definitions/@targetNamespace and the local name in /definitions/portType/@name
Returns:
an array of String representing the list of matching CWSDL XML doc. Empty array if not present.

removeConcreteWsdl

public static void removeConcreteWsdl(ResourceCatalogPortType stub,
                                      javax.xml.namespace.QName query)
Method removeConcreteWsdl. Deletes the CWSDL doc identified by its unique QName

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a CWSDL doc to be deleted. This is given by the namespace /definitions/@targetNamespace and local name /definitions/@name

removeConcreteWsdlByAbstractWsdlQName

public static void removeConcreteWsdlByAbstractWsdlQName(ResourceCatalogPortType stub,
                                                         javax.xml.namespace.QName query)
Method removeConcreteWsdlByAbstractWsdlQName. Deletes all CWSDL documents which have a common AWSDL given by the unique QName for the AWSDL.

Parameters:
stub - a wrapper to a ResourceCatalog webservice
query - a QName uniquely identifying a AWSDL doc whose CWSDLs need to be deleted. This is QName is matched in the CWSDLs with the namespace in /definitions/@targetNamespace and the local name in /definitions/portType/@name

performXQuery

public static java.lang.String[] performXQuery(ResourceCatalogPortType stub,
                                               java.lang.String xquery)
Method performXQuery. This is a generic method used to query for SM, AWSDL, and CWSDL docs in the resource catalog. In the XQuery, the collections containing the SM, AWSDL, and CWSDL are respectively given by the special strings, $SM_COLLECTION, $AWSDL_COLLECTION, and $CWSDL_COLLECTION. The namespaces used in the query will have to be declared in the XQuery prolog. For e.g., to return the CWSDL using it's unique QName {http://tempuri.org]TestService, the XQuery string would be:
 declare namespace wsdl='http://schemas.xmlsoap.org/wsdl/';
 for $cwsdl_doc in collection('$CWSDL_COLLECTION')/wsdl:definitions
 where $cwsdl_doc/@targetNamespace='http://tempuri.org' and $cwsdl_doc/@name='TestService'
   return $cwsdl_doc
 
XQuery functions such as contains, matches, starts-with, ends-with, lower-case, upper-case, etc. can also be used, either prefized by the "fn" namespace prefix, or without a namespace prefix. For more examples of XQueries, see ResourceCatalogClient.testXQueryAPI().

Parameters:
stub - a wrapper to a ResourceCatalog webservice
xquery - a String containing the XQuery to execute at on the resource catalog
Returns:
a String[] containing the results of the XQuery. An empty string array if no results found.


Copyright (c) 2005 Extreme! Lab, Indiana University. All rights reserved.
This software is open source. See here for the licence.