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

java.lang.Object
  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 service map is an XML doc that has a high level definition of a "class" of webservices. This SM, when given to s Service Factory, can be used to create an instance of that "class" of web-service. This doc has a description of the webservice class, the portname and methods it has, and a description of the i/o parameters to the methods. The SM is uniquely identified by a QName whose namespace is present in the attribute /ServiceMap/service/serviceName/@targetNamespace and the local name in the value of the element /ServiceMap/service/serviceName.
• The abstract WSDL is an XML document that defines syntactic information on how to invoke a webservice "class". It conforms to the schema of a WSDL, but does not contain instance related information i.e. the service element. An AWSDL can be created automatically using a SM doc and an AWSDL has to exist for every SM. But all AWSDLs need not have a matching SM. The AWSDL is uniquely identified by a QName, which is also identical to the QName of its SM, if one exists. The namespace is present in the attribute /definitions/@targetNamespace and the local name in the attribute /definitions/@name
• The concrete WSDL is an XML document that defines syntactic information on how to invoke a webservice "instance". It conforms to the schema of a WSDL, and also contain instance related information, such as the endpoint URL present in the service element. A concrete WSDL is sufficient enough to locate and invoke a webservice instance. A CWSDL is uniquely identified by a QName comprising of the namespace present in the attribute /definitions/@targetNamespace and the local name in the attribute /definitions/@name. A CWSDL may have a related AWSDL and by transitivity, a SM also. The QName of the AWSDL and SM for a particular CWSDL is given by the namespace in the attribute /definitions/@targetNamespace and the local name in the attribute /definitions/portType/@name present in the CWSDL document. So the portType names for all CWSDLs for the same AWSDL is the same as the definition name of the AWSDL, and they have the same targetNamespace. Also, the definition name of each CWSDLs for the same AWSDL have to be unique within that set of CWSDLs.

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.