Agreement Monitoring Example

This section provides an example on how to implement agreement monitoring as described in section Agreement Monitoring.

In the WSAG4J framework a new agreement instance is created by a service provisioning plug-in that implements the ICreateAgreementAction. Refer to service instantiation for more information on adding new actions to an agreement factory. The following example uses SampleCreateAgreementAction and SampleAgreement sample classes to demonstrate how a Monitored Agreement is used. The monitoring handler SampleSDTMonitor is used to update the service term and guarantee term states. The SampleAgreement represents a Domain-specific Agreement implementation and extends the AbstractAgreementType class.

The following snippet shows how a monitored agreement is instantiated.

public class SampleCreateAgreementAction extends AbstractCreateAgreementAction {

    public Agreement createAgreement(AgreementOffer offer) throws AgreementFactoryException {
       try {            
            .........
            //
            // create a new instance of a domain-specific agreement implementation
            //
                SampleAgreement sampleAgreement = new SampleAgreement(offer);
            
            //
            // create an instance of a monitored agreement
            //
            MonitorableAgreement monitorAgreement = new MonitorableAgreement(sampleAgreement);
            ...
       }
       catch (Exception e) {
           ...
       }
       ...
   }
}

Instantiating a Domain-specific Agreement

The SampleAgreement is a Domain-specific Agreement implementation as described above. It implements a constructor that takes an agreement offer as argument and calls the appropriate constructor of the parent class.

public class SampleAgreement extends AbstractAgreementType {
  public SampleAgreement(AgreementOffer offer) {
      super(offer);
  }

By creating an agreement instance in that way the state elements of the agreement instance are automatically initialized. By default, for each service description term and guarantee term that is contained in the agreement offer a corresponding service term state and guarantee term state with the same name is created. The constructor AbstractAgreementType(AgreementOffer offer) uses a standard selection strategy for service description terms and guarantee terms. By default all service description terms and guarantee terms defined in an offer are selected and for each selected term a new service term state and guarantee term state is created. Service term states are initially in the NotReady state, while guarantee term states are initially in the NotDetermined state.

Instantiation of a Monitored Agreement by an Agreement Creation Action

Next the Monitored Agreement of WSAG4J framework is instantiated. The domain-specific agreement instantiated before is hereby passed as constructor parameter. The Monitored Agreement updates the agreement state, the service term states and the guarantee term state of the domain-specific agreement instance in each monitoring cycle. The following code snippet shows how a Monitored Agreement is instantiated.

MonitorableAgreement monitorAgreement = new MonitorableAgreement(sampleAgreement);

Now a set of monitoring handlers can be configured for the Monitored Agreement. The monitoring handlers provide the domain specific logic to update the agreement service term states. They retrieves the current state of the provided services and implement the business logic to update the service terms states accordingly. It is considered as best practice that one monitoring handler updates one service term state. However, one monitoring handler may also update multiple service term states. The following snippet shows how a monitoring handler is added to a Monitored Agreement.

monitorAgreement.addMonitoringHandler(new SampleSDTMonitor());

The monitoring handlers are invoked by the Agreement Monitor based on the monitoring schedule that defines the monitoring intervals. The monitoring schedule is configured for each monitored agreement instance individually by specifying a Cron expression. See Cron trigger documentation for a detailed description. The registered monitoring handlers are invoked once each monitoring cycle. The following example defines a monitoring interval of 30 seconds.

String cronExpression = "0/30 * * * * ?";
monitorAgreement.setCronExpression(cronExpression);

It is possible to register a set of implementation-specific properties with a Monitored Agreement. These properties can be accessed by the monitoring handlers at runtime via the Monitoring Context. The following example shows how these Execution Properties are added.

monitorAgreement.getExecutionContext().getExecutionProperties().put(SampleCreateAgreementAction.SAMPLE_OFFER, sampleOffer.getXMLObject());

In order to start the monitoring process the startMonitoring() method needs to be called. Based on the defined Cron expression it can take some time until the states are updated.

monitorAgreement.startMonitoring();

Implementation of a custom Monitoring Handler

As described above, the SampleSDTMonitor monitoring handler is added to the Monitored Agreement. The Agreement Offer is created from the sample template. Please have a look on the Template Design section for a detailed description of the template. The first service description term called RESOURCE_STD contains a JSDL document that specifies the total number of free resources.

<wsag:ServiceDescriptionTerm wsag:Name="RESOURCE_STD" wsag:ServiceName="SAMPLE-NEGOTIATION_SERVICE">
        <jsdl:JobDefinition xmlns:jsdl="http://schemas.ggf.org/jsdl/2005/11/jsdl">
        <jsdl:JobDescription>
                <jsdl:Resources>
                <jsdl:CandidateHosts>
                        <jsdl:HostName>some_host</jsdl:HostName>
                </jsdl:CandidateHosts>
                <jsdl:TotalResourceCount>
                        <jsdl:Exact>10</jsdl:Exact>
                </jsdl:TotalResourceCount>
            </jsdl:Resources>
        </jsdl:JobDescription>
    </jsdl:JobDefinition>
</wsag:ServiceDescriptionTerm>

The second service description term called TIME_CONSTRAINT_SDT contains a time constraint document that specifies the time period for which the resources are available for reservation.

<wsag:ServiceDescriptionTerm wsag:Name="TIME_CONSTRAINT_SDT" wsag:ServiceName="SAMPLE-NEGOTIATION_SERVICE">
        <wsag4jt:TimeConstraint xmlns:wsag4jt="http://schemas.wsag4j.org/2009/07/wsag4j-scheduling-extensions">
        <wsag4jt:StartTime>2011-07-01T12:00:00</wsag4jt:StartTime>
        <wsag4jt:EndTime>2011-07-01T13:00:00</wsag4jt:EndTime>
        <wsag4jt:Duration>60</wsag4jt:Duration> <!-- duration in minutes -->
    </wsag4jt:TimeConstraint>
</wsag:ServiceDescriptionTerm>

When the Domain-specific Agreement is instantiated all corresponding service term states are created for these service description terms. They are in the NotReady state before the monitoring handlers are invoked:

<ws:ServiceTermState ws:termName="RESOURCE_STD">
        <ws:State>NotReady</ws:State>
</ws:ServiceTermState>
<ws:ServiceTermState ws:termName="TIME_CONSTRAINT_SDT">
    <ws:State>NotReady</ws:State>
</ws:ServiceTermState>

The SampleSDTMonitor implements the IServiceTermMonitoringHandler interface, that has one abstract method monitor(IMonitoringContext context), which is implemented by the monitoring handler to update the status of the RESOURCE_STD and TIME_CONSTRAINT_SDT service term states.

In the snipped below the resources definition document in RESOURCE_STD service term state is initialized and the reserved host name is updated. Also the TIME_CONSTRAINT_SDT service term state is initialized with a time constraint document and updated to the actual reservation time.

public void monitor(IMonitoringContext context) throws Exception {
        
        try {
                
            //
            // retrieves the Service Term State by its name
            //
            ServiceTermStateType resourcesServiceTerm = context.getServiceTermStateByName("RESOURCE_STD");
            ResourcesType resources = loadResourcesDefinition(resourcesServiceTerm);
            resources.set(getOfferResources(context));
            //
            // setting the target host name which has been reserved for a required time frame
            //
            resources.getCandidateHosts().setHostNameArray(0, "reserved_target_host");
            
            ServiceTermStateType timeServiceTerm = context.getServiceTermStateByName("TIME_CONSTRAINT_SDT");
            TimeConstraintType timeFrame = loadTimeConstraint(timeServiceTerm);
            timeFrame.set(getOfferTimeConstraint(context));
            
            //
            // once reservation is finished, corresponding service term state(s) can be set to COMPLETED 
            //
            resourcesServiceTerm.setState(ServiceTermStateDefinition.COMPLETED);
            timeServiceTerm.setState(ServiceTermStateDefinition.COMPLETED);
                
        } catch (Exception e) {
            ........
        }
}

After invocation of the monitoring handler, the RESOURCE_STD and TIME_CONSTRAINT_SDT service term states are updated with resource definition document and reserved host name as shown below:

<ws:ServiceTermState ws:termName="RESOURCE_STD">
        <ws:State>Completed</ws:State>
    <jsdl:JobDescription xmlns:jsdl="http://schemas.ggf.org/jsdl/2005/11/jsdl">
        <jsdl:Resources>
                <jsdl:CandidateHosts>
                <jsdl:HostName>reserved_target_host</jsdl:HostName>
                </jsdl:CandidateHosts>
                <jsdl:TotalResourceCount>
                <jsdl:Exact>10</jsdl:Exact>
            </jsdl:TotalResourceCount>
        </jsdl:Resources>
    </jsdl:JobDescription>
</ws:ServiceTermState>

It is important to note that the monitoring handlers are updating a working copy of the agreement resource properties document. When a monitoring cycle is started, a copy of the agreement resource properties document is created. This copy is then updated by the Monitored Agreement and the registered monitoring handlers. Once the monitoring cycle is completed, the agreement resource properties of the Domain-specific Agreement are replaced with the updated copy.

Query the agreement state from a client application

The agreement states can be queried from a client application. Refer to the client documentation for this purpose.