(It will be clear [[#WS-Resources and The Implied Resource Pattern|soon]] why we prefer two port-types with a single operation each rather than a single port-type with two operations.)

How should we go about creating and accessing stateful resources?  One approach could be as follows:

* take some credentials from clients when they invoke the <code>logon()</code> operation on the <code>Factory</code> port-type. A simple name would surely do for our purposes.  

* create stateful resources as Java objects that contain the count of client visits, and identify such resources with the name of the associated client.  

In this approach, clients need to explicitly identify the state they wish to target. Unfortunately, identifiers are service-specific: here we need a name, elsewhere we may need something different. The use that we make of identifiers is also specific: here we hinted at one parameter in the <code>aboutSF()</code> operation, elsewhere could be two or three parameters in one or more operations. This variability makes it impossible to build generic clients that can transparently access state across different services.

 

You may find this observation rather strange: what could a client do that does not require specific knowledge of the target service? Well, it turns out that if we find a general way to access stateful resources, then we can build enough conventions on how we describe them to enable a range of very useful and yet generic clients. For example, we can define clients that can query and change the stateful resources of any service that complies with the conventions. We can define clients that can uniformly destroy stateful resources, either immediately or based on some renewable expiry time. We can even define clients that allow others to subscribe for changes to the stateful resources. These are all key features in gCube, and we shall be directly concerned with some of them in this very Primer.  

What we need to promote generic clients is then:

* a uniform pattern to identify and access stateful resources which does not change from service to service.  

* a standard that codifies this pattern and builds useful conventions on top of it.

The [http://www.oasis-open.org/committees/wsrf Web Services Resource Framework (WSRF)] is precisely one such standard, and gCube adopts it. When it comes to identifying and accessing stateful resources, WSRF says: forget passing identifiers explicitly in operations such as <code>aboutSF()</code>, which vary from port-type to port-type and from service to service; let us pass them instead ''implicitly'', as part of the address of the port-type that exposes those operations. An invocation of <code>aboutSF()</code> would thus be addressed to the <code>Stateful</code> port-type, but the address would include also the identifier of the stateful resource that is the target of the request. The port-type implementation would then extract such identifier and use it to locally access the stateful resource. No need to explicitly parameterise <code>aboutSF()</code> with it. This is the access pattern that WSRF calls the ''implied resource pattern''.

If you think about it, this annotated address - or more appropriately, this ''qualified endpoint reference'' - identifies a pair (port-type,stateful resource). WSRF calls this pair a ''WS-Resource''. We can then think of the qualified endpoint reference as the endpoint reference of the WS-resource itself. Similarly, we can think of the operations available at that endpoint as the operations of the WS-Resource. In this sense, the port-type becomes the uniform interface of potentially many WS-Resources.

With the implied resource pattern and the corresponding terminology, we can now describe our new port-types as follows:

* a <code>Stateful</code> port-type that defines the interface of the WS-Resources. We plan a single operation for this port-type too, <code>aboutSF()</code>, which takes nothing but it is invoked with the endpoint reference of a WS-Resource.

A client may then invoke <code>logon()</code> on the <code>Factory</code> port-type and then use the resulting WS-Resource endpoint reference to invoke <code>aboutSF()</code> on it. As we shall see, a client may also ''discover'' and use the endpoint of a WS-Resource of interest without having previously created it. A couple of things to notice:

[[Image:blue.jpg]] The client does not need to know about the stateful resource identifier embedded in the endpoint reference returned by the <code>Factory</code>, or otherwise 'found'. The endpoint reference identifies a WS-Resource but the inner structure of this WS-Resource as a pair (port-type,stateful resource) remains opaque to the client.

[[Image:blue.jpg]] Placing <code>logon()</code> and <code>aboutSF()</code> in different port-types makes sense. The first creates WS-Resources while the second defines their operations. Informally, we say that the <code>Factory</code> is, like <code>Stateless</code>, a ''stateless port-type'' because it does not serve as the interface of WS-Resources. For the opposite reason, we say that <code>Stateful</code> is a ''stateful port-type''.

=== Extending the Profile ===

=== More Port-Type Interfaces ===

 

<xsd:import namespace="http://schemas.xmlsoap.org/ws/2004/03/addressing"  

                                                    schemaLocation="../ws/addressing/WS-Addressing.xsd" />

 

Just notice the following:

[[Image:blue.jpg ]] At this stage, there is little point in looking into the schema definition of this type. gCore will offer Java objects to model and serialise qualified endpoint references, in accordance with the schema definition. We just notice here that the stateful resource identifier that qualifies an endpoint reference of a WS-Resource is an XML document with an arbitrary payload. In jargon, we speak of this element as the ''key'' of the stateful resource. In gCF, in particular, the payload of resource keys is always a plain string, such as the 'name' of clients we expect to use in the design of our <code>Sample</code> service.

 

The WSDL for the <code>Stateful</code> port-type is also straightforward, at least for the time being.

     <import namespace="http://gcube-system.org/namespaces/common/core/faults" location="../gcube/common/core/faults/GCUBEFaults.wsdl"/>

     

            <xsd:import namespace="http://gcube-system.org/namespaces/common/core/types"  

                                        schemaLocation="../gcube/common/core/types/GCUBETypes.xsd"/>

      <xsd:element name="aboutSF" type="coretypes:VOID" />

    <xsd:element name="aboutSFResponse" type="xsd:string" />          

Just notice the following:

 

[[Image:blue.jpg ]] The operation <code>aboutSF()</code> takes an instance of type <code>VOID</code> as a way to say that it takes nothing of interest. In particular, notice how the operation does ''not'' need any explicit information to identify the stateful resource that corresponds to the requesting client; as discussed [[#WS-Resources and The Implied Resource Pattern |earlier]] the identifier will be implicitly carried by the request, in accordance with the implied resource access pattern. As to the type <code>VOID</code>, this is imported from a schema document that ships with gCore (<code>GCUBETypes.xsd</code>), again relatively to the location of the interface ''after'' service deployment. The schema defines <code>VOID</code> and other common types, for your convenience and to promote uniform conventions in gCube.

 

Now store the new interfaces in the schema folder under the service location. Remember that file names and port-types must coincide:

|---Factory.wsdl         [new]

|---Stateful.wsdl         [new]

=== Stateful Resources ===

Time to model stateful resources then. Inspiringly, we shall do this with objects of a <code>Resource</code> class. The minimal requirements on this class are indeed minimal:

[[Image:red.jpg]] it '''must''' extend a class provided by gCF, <code>GCUBEWSResource</code>.

[[Image:red.jpg]] it '''must''' implement <code>initialise()</code>, the only abstract method of <code>GCUBEWSResource</code>.

Here's a glorious Java class that does just that:

package org.acme.sample.stateful;

public class Resource extends GCUBEWSResource {

     /** Client visits.*/

    /**{@inheritDoc}*/

     public void initialise(Object... args) throws Exception {

        if (args == null || args.length>1) throw new IllegalArgumentException();

        this.setName((String) args[0]);

     public String getName() {return name;}

 

    public synchronized int getVisits() {return visits;}

     protected synchronized void addVisit() {this.visits++;}

As you can see, there is little that you ''have'' to do to extend <code>GCUBEWSResource</code>. gCF will invoke <code>initialise()</code> in the process of creating a new WS-Resource. The single parameter is an array of zero or more parameters that might be required to initialise a stateful resource (here modelled as an optional parameter for the convenience of clients that have no parameters to pass). Here we expect the name of the client associated with the resource (the client whose visits the resource will track). We perform some checks on the input parameters (there must be exactly one), and then use it to initialise the resource in the obvious way.

[[Image:blue.jpg]] <code>initialise()</code> works a bit like the <code>main()</code> method of standard a Java application, except that it takes <code>Object</code>s rather than <code>String</code>s. In the latter case, the parameters are typically specified on the command line, here you will pass them in from some other part of the code, where the decision to create a WS-Resource is first made. Remember that according to our [[#WS-Resources and The Implied Resource Pattern|plans]] we will do it from the implementation of the <code>Factory</code> port-type and in response to explicit client requests.

[[Image:blue.jpg]]  <code>Resource</code> inherits far more state and behaviour than it declares. We will unveil a small part of this heirloom as we go along. For now, we only notice that the stateful resource inherits an identifier and that the inherited method <code>getID()</code> is available to show it. The precise nature of this identifier depends on how the WS-Resource is created, and we will discuss it later when implementing the <code>Factory</code> port-type.

[[Image:blue.jpg]] Even the simplest of stateful resources must be ready for concurrent access. Although not exactly likely for our <code>Sample</code> service, many clients may target the same WS-Resource at the same time. Concurrent client visits will be assigned different threads by gCore and different threads might concurrently access the same stateful resource through the <code>addVisit()</code> and <code>getVisits()</code> methods. If we did not synchronise access to either of these methods our counter may then become inconsistent. Concurrency is of course a main concern when implementing a service and it is not something gCF can entirely abstract away for you.

|---profile.xml

|---deploy-jndi-config.xml

|---deploy-server.wsdd

|---build.properties

|-------Resource.java          [new]

|-------StatelessTest.java

|---Stateless.wsdl

According to our [[#WS-Resources and The Implied Resource Pattern|plans]], the <code>Factory</code> port-type will create <code>Resource</code>s and the <code>Stateful</code> port-type will find them, use them, and change them.  

Find them from where, exactly? We could hold a repository of <code>Resource</code>s in the implementation of the <code>Stateful</code> port-type, but a cleaner and more general approach is to have a dedicated manager of <code>Resource</code>s that can be accessed from multiple port-types and for different purposes. In gCF, managers of stateful resources are called ''resource homes''.

Writing a simple resource home is as simple as writing a simple stateful resource. However, we cannot do it as incrementally. Along with the resource home we have to introduce a context for the associated port-type, <code>Stateful</code> in our case. Only so will gCF be able to link all the pieces required for state management on our behalf. In particular:

Let us start from the home anyway:

import ...

     /** {@inheritDoc} */

     public GCUBEStatefulPortTypeContext getPortTypeContext() {return StatefulContext.getContext();}

}  

 

[[Image:red.jpg]] The home implementation '''must''' extend a class provided by gCF, <code>GCUBEWSHome</code>.

 

[[Image:red.jpg]] The home implementation '''must''' implement <code>getPortTypeContext()</code>, the only abstract method of <code>GCUBEWSHome</code>.

 

Here we return the singleton instance of <code>StatefulContext</code>, where <code>StatefulContext</code> is defined as follows:

 

public class StatefulContext extends GCUBEStatefulPortTypeContext {

     /**Creates an instance, privately. */

    private StatefulContext(){}

    /* @return the context.*/

    public static GCUBEStatefulPortTypeContext getContext() {return cache;}

 

    public String getJNDIName() {return "acme/sample/stateful";}

 

     /** {@inheritDoc} */

    public String getNamespace() {return "http://acme.org/sample";}

    /** {@inheritDoc} */

     public GCUBEServiceContext getServiceContext() {return ServiceContext.getContext();}

There is not much we have not [[Refining the implementation#Node & Port-Type Contexts|already seen]] here:

* we follow the usual singleton pattern by returning always a single, eagerly created instance.  

* we follow the usual template pattern to indicate the JNDI configuration entry-point for the associated port-type (<code>getJNDIName()</code>), the namespace in which the interface of the port-type was declared (<code>getNamespace()</code>), and the context of the associated service (<code>getServiceContext()</code>).  

 

[[Image:red.jpg]] The contexts of stateful port-types '''must''' extend the <code>GCUBEStatefulPortTypeContext</code>, rather than the more general <code>GCUBEPortTypeContext</code>. The latter gCF class will provide our context with the additional behaviour which is required by the underlying assumption of state.

 

 

 

<resource name="home" type="org.acme.sample.stateful.Home">

              <name>factory</name>

              <value>org.globus.wsrf.jndi.BeanFactory</value>

          </parameter>

                <value>org.acme.sample.stateful.Resource</value>

 

 

[[Image:red.jpg]] The JNDI section contains a distinguished <code>resource</code> element that configures the resource home associated with the port-type. The terminology is a bit unfortunate here: this <code>resource</code> is a 'JNDI resource', nothing to do with a stateful resource! Along with the <code>environment</code> elements you have seen so far, it is one of the [[Configuration Components#The JNDI Configuration|two modelling primitives]] that we can use to structure information within JNDI fields. Hopefully, this will not be too confusing.

 

[[Image:red.jpg]] The <code>resource</code> element '''must''' have a <code>name</code> attribute with value <code>home</code>. Only so, can this JNDI resource be identified as the configuration of the resource home associated with the port-type. Then it '''must''' have a <code>type</code> that specifies the fully qualified name of the resource home implementation, <code>org.acme.sample.stateful.Home</code> in our case;

 

[[Image:red.jpg]] The <code>resource</code> element '''must''' be configured with at least a small number of <code>resourceParams</code>. The first <code>resourceParam</code> specifies a <code>factory</code> that can create an instance of the resource home we are configuring. The value of this <code>resourceParam</code> is normally always the same, a pre-defined bean factory that ships with gCore. This factory expects the resource home implementation to expose setters for all the other <code>resourceParam</code>s that occur under <code>resourceParams</code>. The <code>GCUBEWSHome</code> derived by our <code>Home</code> guarantees that this is the case for all the parameters that are pre-defined in gCore (if you were to add ad-hoc configuration parameters in your resource home, then your home implementation would have to include setters for these too). In most cases, you will stick with this factory implementation. We will surely do in this Primer!

 

[[Image:red.jpg]] The <code>resourceParams</code> '''must''' include a <code>resourceParam</code> called <code>resourceClass</code> that indicates the fully qualified name of the class that implements the stateful resources managed by the resource home. This allows your home to create your stateful resource objects reflectively. Here we specify <code>org.acme.sample.stateful.Resource</code> of course but we do not need to worry about using it directly. The <code>GCUBEWSHome</code> we inherited from gCF will do it for us at the right time.

 

[[Image:blue.jpg]] Since we are at it, we are throwing in some service-specific configuration, here a numeric threshold beyond which clients will belong to a Frequent User club. This is rather silly but reminds you that port-type contexts are there for your own configuration as well as the configuration required by gCF. We will use this configuration [[#The Stateful Port-Type|soon]] from the implementation of the <code>Stateful</code> port-type.

 

In conclusion, we have added two more pieces to the implementation of <code>Sample</code>, a <code>Home</code> to manage <code>Resource</code>s and a <code>StatefulContext</code> for the <code>Stateful</code>. We have also added JNDI configuration for the <code>Stateful</code> port-type, particularly information about the associated <code>Home</code>. The implementation of <code>Sample</code> now look as follows:

 

|---deploy-jndi-config.xml     [changed]

|-------Resource.java        

|-------Home.java             [new]

|-------StatefulContext.java   [new]

=== The Factory Port-Type ===

 

With <code>Resource</code>, <code>ResourceHome</code>, and <code>StatefulPortTypeContext</code> our back-end for state management is in place. What we are left with is now to make co-ordinate use of these classes in the implementation of the <code>Factory</code> and <code>Stateful</code> port-types.

 

Starting with the <code>Factory</code> port-type:

package org.acme.sample.stateful;

import...

GCUBELog logger = new GCUBELog(this);

/** {@inheritDoc} */

protected ServiceContext getServiceContext() {return ServiceContext.getContext();}

As we have [[The Development Cycle#A Simple Implementation|already seen]] for the <code>Stateless</code> port-type, our <code>Factory</code> implementation extends <code>GCUBEPortType</code> and implements the <code>getServiceContext()</code> method.

 

As to the method <code>logon()</code>, notice what follows:

 

 

[[Image:blue.jpg]] We obtain the singleton instance of the <code>StatefulContext</code> port-type and use it to retrieve the associated resource home. The method <code>getHome()</code> is defined in <code>GCUBEStatefulPortType</code> and our <code>StatefulContext</code> has simply inherited it. The JNDI configuration of the port-type has provided enough information to gCF to implement that method on our behalf. Note also that since our <code>Home</code> does not add any behaviour to the generic <code>GCUBEWSHome</code> (nor would we need it here), we do not need to cast the return value of <code>getWSHome()</code> to <code>Home</code> but can work directly with the supertype <code>GCUBEWSHome</code>.

 

[[Image:blue.jpg]] We ask the home to create a stateful resource by invoking the method <code>create()</code> on it. This method is predefined in <code>GCUBEWSHome</code> (and thus in our <code>Home</code> that inherits from it). It appears to return a generic <code>GCUBEWSResource</code> but there is a more specific <code>Resource</code> underneath. The home has looked into the JNDI configuration of the port-type to know which class to instantiate reflectively (remember the <code>resourceClass</code> configuration parameter?). In any case, we do not need to do anything specific with this resource, so we can again leave it at that without needing to cast down to the more specific <code>Resource</code>.

 

[[Image:blue.jpg]] We invoke <code>create()</code> with the identifier that we wish to give to the stateful resource and the parameters required to initialise it, here only the name of the client. This identifier is based on the <code>name</code> parameter provided by the client but it's actually a <code>GCUBEWSresourceKey</code> wrapper that we can ask the <code>StatefulContext</code> to produce for us. The reason of wrapping our identifier into a 'key' is because we need to return it to the client and thus it needs to serialise on the wire in accordance with WS-Addressing requirements for endpoint reference qualifications. Notice that we have [[#WS-Resources and The Implied Resource Pattern|already introduced]] the notion of a WS-Resource key, check it out.  

 

[[Image:blue.jpg]] Finally, we invoke the method <code>getEPR()</code> on our resource. The method is predefined in <code>GCUBEWSResource</code> and returns the endpoint reference of the WS-Resource that encapulates our resource. Then we simply return the endpoint reference to the client.

 

A couple of extra commonents on <code>create()</code>:

 

[[Image:blue.jpg]] <code>create()</code> can accept an arbitrary number of resource initialisation parameters. If more were required, we would pass them all after the key, comma-separating them (or as an array). As we have seen [[Stateful_Resources|earlier]] these parameters will end up into the <code>initialise()</code> method of the <code>Resource</code> class. Similarly, we could pass zero initialisation parameters (i.e. only the key) if the resource did not need any at all to initialise.

 

[[Image:blue.jpg]] the <code>create()</code> could have also ''not'' taken a key at all (only parameters or absolutely nothing). In this case, the home would have automatically generated a key for the resource. The decision of whether to specify an identifier or not is our own to make. If we specify one, then the home will avoid creating a fresh resource ''if'' there is already one with that identifier. So, we specify a key any time we wish to ''reuse'' resources across 'semantically equivalent' requests. If this is not the required behaviour, i.e. we do not want reuse of stateful resources, then we do not pass a key to <code>create()</code>. This depends of course on the semantics of our service; if reuse is a sensible option we should strive for it, as creating stateful resources might be in principle arbitrarily expensive processes. Here, rather artificially, we assume that the name is an unambiguous identifier for clients (...) and decide that if we receive many requests with the same name then we will associate all of them with the same WS-Resource.

 

 

Finally we come to the consumption of WS-Resources and thus to the implementation of the <code>Stateful</code>:

 

<pre>

 

 

    private final String THRESHOLD_JNDI_NAME="frequentUserThreshold";

 

 

 

          ServiceContext sctx = ServiceContext.getContext();

          StatefulContext pctx = StatefulContext.getContext();

 

 

 

            output.append("\nThis is your invocation N." + resource.getVisits() + "\n");

            int threshold = (Integer) pctx.getProperty(THRESHOLD_JNDI_NAME);

            if (resource.getVisits() >= threshold) output.append("welcome in the frequent user club!");

 

 

 

 

 

There are essentially two things to notice here:

 

[[Image:blue.jpg]] the method <code>aboutSF()</code> behaves like <code>about()</code> in the implementation of the <code>Stateless</code> port-type (check any of the versions we have looked at before). The significant difference is that now we are acting in the context of a WS-Resource and thus upon an underlying stateful resource. We know by now that this resource will be implicitly identified in the endpoint reference use to call this WS-Resource, and we delegate the task to retrieve it to a private helper method <code>getResource()</code>. Assuming we get one back, we increment its count of client visits and proceed with satisfying the client request. In particular, we append the current count of visits at the end of the message, consult port-type configuration via its context to decide whether we should also welcome the client to the frequent user club, and finally  return the message to the client.

 

[[Image:blue.jpg]] in <code>getResource()</code>, we delegate in turn the task to retrieve the stateful resource to the resource home, which we obtain from the context of the <code>Stateful</code> port-type. We then ask the home to find the required resource, by invoking a method <code>find()</code> that our <code>Home</code> inherits from <code>GCUBEWSHome</code>. As the invocation specifies no parameters, the home resolves it by automatically extracting the endpoint reference with which the current call was made by the client. It will then look into that reference and extract the stateful resource key and use the key to lookup the required resource. As this operation is a general one defined by <code>GCUBEWSHome</code>, its return type is as generic as <code>GCUBEWSResource</code> and, since we plan to invoke <code>Resource</code>-specific methods, we need to down cast it before we can return a specific <code>Resource</code>.

 

[[Image:blue.jpg]] in the process of implied resource access, a few things could go wrong. The call may have been made with an unqualified endpoint reference, i.e. might have been addressed to the port-type rather than a WS-Resource that encapsulates the port-type. Even if the endpoint reference is qualified with a key, the home may still fail to find a resource with that key. This could be because one such resource never existed (the endpoint reference was somehow incorrectly built), or because it existed but it has somehow been removed. We will return later to this possibility.

 

 

With our two new port-type implementations, the service implementation ought to look as follows:

|-------Resource.java        

|-------Home.java            

|-------StatefulContext.java  

|-------Factory.java           [new]

|-------Stateful.java         [new]

=== Building & Deploying ===

 

 

 

 

<deployment name="defaultServerConfig" xmlns="http://xml.apache.org/axis/wsdd/"

                        xmlns:java="http://xml.apache.org/axis/wsdd/providers/java" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    </service>

 

    <service name="acme/sample/factory" provider="Handler" use="literal" style="document">

         <parameter name="className" value="org.acme.sample.stateful.Factory"/>

         <wsdlFile>share/schema/org.acme.sample/Factory_service.wsdl</wsdlFile>

    <service name="acme/sample/stateful" provider="Handler" use="literal" style="document">

         <parameter name="className" value="org.acme.sample.stateful.Stateful"/>

         <wsdlFile>share/schema/org.acme.sample/Stateful_service.wsdl</wsdlFile>

 

Now [[The Development Cycle#Building & Deploying|build and deploy]] service and stubs. As to the service implementation, the latest snapshot is as follows:

 

|---deploy-server.wsdd       [changed]

|---build.properties         [changed] 

|-------Resource.java        

|-------Home.java            

|-------StatefulContext.java  

|-------Factory.java        

|-------Stateful.java        

package org.acme.sample.tests;

import ...

 

    static GCUBEClientLog logger = new GCUBEClientLog(StatefulTest.class);

      logger.info("visiting WS-Resource...");

 

        FileReader reader = new FileReader("/tmp/resource.epr");

        EndpointReferenceType resourceEPR=  

              (EndpointReferenceType) ObjectDeserializer.deserialize(newInputSource(reader),EndpointReferenceType.class);

        reader.close();

        StatefulPortType stub = new StatefulServiceAddressingLocator().getStatefulPortTypePort(resourceEPR);

 

Here, we deserialise the resource following a process inverse to its serialisation (just take this code as boiler plate, really). The rest ought to be familiar by now, including the expectation of a scope as a test parameter.

 

Now, run <code>CreateResource</code> once and then <code>StatefulTest</code> multiple times to see the count of visits growing at each call.

 

With the two test clients, the service implementation ought to look as follows:

 

|---deploy-jndi-config.xml    

|-------Resource.java        

|-------Home.java            

|-------StatefulContext.java  

|-------Factory.java  

|-------Stateful.java  

== WS-Resources and Standard Interfaces ==

 

=== WS-Resource Properties ===

 

WSRF proposes a standard for exposing state as an unordered set of [http://www.ibm.com/developerworks/library/specification/ws-resource/ws-resourceproperties.pdf Resource Properties]. A Resource Property, or RP for short, is any piece of information that we wish to make ''public'' about our WS-Resources. A RP may be statically or dynamically computed, it may be constant or else change over time or not, it may occur once or many times, and it may or may not have internal structure. What it does matter is that a RP has a ''name'' that clients can use to refer to it.

 

In our example, we may decide to consider the name of the client associated with a WS-Resource as a single-valued and constant RP. Instead, we may decide to consider the number of client visits as a piece of private state and not expose it as a RP at all. In fact, unknown to us, our WS-Resources already include some 'hidden' state modelled as RPs. gCF augmented them implicitly with RPs that describe various systemic properties of the WS-Resources (e.g. the scope in which they operate, the identifier of the gHN in which they are hosted, the name and class of the service to which they belong, etc.). Collectively, we refer to these pre-defined RPs as the ''gCube RPs''.

 

gCube RPs and service-specific RPs collectively form the public state of our WS-Resources, something that generic clients can target without knowing anything more specific about our WS-Resources. To actually act upon our WS-Resource, WSRF also defines standard interfaces with which clients can access, query, and change RPs. gCube has in turn implemented many key infrastructure-wide mechanisms that make use of these interfaces, and thus is important that our WS-Resources implement them. We don't need to worry too much about the cost of compliance, however, because gCF offers pre-defined implementations that can be 'plugged' into our services. Effectively, these implementations ''extend'' the stateful port-types with support for the operations defined in the WSRF interfaces. In particular, gCF defines one such implementation, called the ''gCube Provider'', that supports the minimal set of WSRF operations that are mandatory for the WS-Resource of ''all'' gCube services.

 

 

 

After completing these three steps we will have added the operations of the gCube Provider to the stateful port-type and will have linked them to the implementation of our stateful resources. In other words, clients will be able to invoke the operations of the gCube Provider and the implementations of these operations will be able to access our stateful resources.

 

 

 

 

[[Image:red.jpg]] we '''must''' first include a schema description of the available RPs in the WSDL of the port-type, where a generic client that obtains the WSDL can in principle discover them. This effectively amounts to describing the public state of our WS-Resources as a well-formed XML document, what WSRF calls the ''Resource Property Document'' (RPD). The RPD description is always a global, complex element which we are otherwise free to name. In our case, the element is called <code>statefulRPD</code> and includes the description of a single-valued RP called <code>Name</code>:

[[Image:red.jpg]] we '''must''' add two special attributes to the <code>portType</code> element of the WSDL. The first points generic clients to the <code>statefulRPD</code> element, so that they can identify it within the WSDL. The second indicates our will to extend the port-type interface with the operations defined in the WSDL of the gCube Provider. Clearly, we need also to import the new namespaces that come into play and bind them to some suffixes in the top-level <code>definitions</code> element of the WSDL:

<definitions name="Stateful"

    ....

    xmlns:wsdlpp="http://www.globus.org/namespaces/2004/10/WSDLPreprocessor"

    xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"

    xmlns:provider="http://gcube-system.org/namespaces/common/core/porttypes/GCUBEProvider">

    ...

  <import namespace="http://gcube-system.org/namespaces/common/core/porttypes/GCUBEProvider" location="../gcube/common/core/providers/GCUBEProvider.wsdl"/>

  ...

</pre>

 

We now move to extending the implementation of the <code>Stateful</code> port-type with the implementation of the gCube Provider. This will not require us to change any code, only the deployment descriptor of the <code>Stateful</code> port-type. In particular:

 

[[Image:red.jpg]] we '''must''' add the following <code>parameter</code> to the <code>service</code> dedicated to the port-type (in no particular place):

 

 

That's it. Now when the operations of the gCube Provider are invoked on our <code>Stateful</code> port-type their original implementations will be found and executed.

 

 

One last step to complete the integration of the gCube Provider in our service implementation: when an operation of the gCube Provider is invoked on our <code>Stateful</code> port-type, its implementation will try to access our stateful resources. The problem is that it will do so in terms of the abstractions it knows about, namely RPs.

Although our <code>Resource</code> class defines a <code>String</code>-valued field that corresponds to the <code>Name</code> RP we have declared in the WSDL, the gCube Provider has no idea that this field corresponds to the RP, nor does it know what fields correspond to RPs and what fields are instead meant to be private state.

 

 

[[Image:blue.jpg]] indicate the names of the RPs. We do so by overriding the method <code>getPropertyNames()</code> inherited from <code>GCUBEWSResource</code> and returning the names into an array of <code>String</code>s:

 

...

 

protected String[] getPropertyNames() {return new String[]{NAME_RP_NAME};}

 

 

public synchronized String getName() {

  return (String) this.getResourcePropertySet().get(NAME_RP_NAME).get(0);

=== More Testing ===

 

After a new build and deployment of the service, we are ready to test the novelties. Here, we pretend to be generic clients and check whether the RPs of our WS-Resources can be accessed using the generic WSRF interfaces. In practice, we may well never need to act as generic clients. And yet some of the services we might interact with may take advantage of the standard interfaces and offer no other means to explore the state of their WS-Resources; in other words, they may treat specific and generic clients in the same way (no methods like <code>getName()</code> on their port-type interfaces!). In any case, we need to test that we are truly compliant with WSRF and gCube requirements.

 

 

StatefulPortType statefulPT = new StatefulServiceAddressingLocator().getStatefulPortTypePort(..some-endpoint-reference..);

 

 

              <ns1:Name xmlns:ns1="http://acme.org/sample">...the current value of the RP...</ns1:Name>

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

[[Image:blue.jpg]] At the server's side, the gCube Provider executes the operation by invoking a method <code>remove()</code> that our <code>Home</code> inherits from <code>GCUBEWSHome</code>. You can also invoke this method from within the service implementation if, for some conditions that are specific to the semantics of your WS-Resources, you can conclude that it's time to remove any given one from one or more of its scopes.