In the WSAG4J framework agreements are created based on specific templates. A client can query the supported agreement templates from an agreement factory. It the creates a new agreement offer based on a suitable template. The resulting agreement offer can then be modified by the client. Finally the offer is send to the agreement factory that creates a new agreement instance is the offer is accepted.
You can compare agreement templates to classes in object-oriented programming languages. They define restrictions on valid agreement offer by their creation constraints. Moreover, they can specify guarantees and the way how these guarantees are evaluated at runtime. Since in the WSAG4J framework each agreement must be created on a template exposed by an agreement factory, a template corresponds to the concept of a class in an object-oriented programming language, while a particular agreement instance corresponds to the concept and agreements correspond of an instance of this class. Refer to the guide to agreement template design more details on how templates are created.
When a WSAG4J agreement factory receives a create agreement request, it first looks up the template that was used for creating the agreement offer. This template must be specified within the agreement offer's context element. If this is not the case, the offer is rejected. Each template is uniquely identified by its name and its template id. The template name specifies the SLA type (class) and the template id specifies the template version. Together, these two identifiers specify the server action that is used used to create an agreement.
A WSAG4J factory action consist of the following 3 parts:
Each of the above mentioned strategies implement domain-specific functionality that can be configured and plugged into a WSAG4J server.
The WSAG4J framework supports multiple factory actions per agreement factory. Each factory action has a template creation strategy, a negotiation strategy, and an agreement creation strategy. The template creation strategy returns exactly one agreement template. The template name and template id uniquely identify the factory action with an agreement factory instance. This means that the negotiation strategy and the agreement creation strategy are identified by this unique id (template name:template id) within the agreement factory instance. This mapping is illustrated below.
As mentioned before, a particular negotiation strategy is invoked for negotiation offers that are based on the template generated by the corresponding template creation strategy of a server action. Accordingly, the agreement creation strategy of server action is invoked for agreement offers that are based on the template generated by the associated agreement creation strategy. When a client creates an agreement offer (negotiation offer) based on an agreement template it must reference this template within the Context element of the offer. When the WSAG4J server receives such an offer it first looks up the referenced template and validates the offer against the creation constraints defined in the template. Then it looks up the corresponding factory action, which is identified by the template name and id. Finally it invokes the according agreement creation strategy of the server action. This process is shown in the picture below.
The template creation strategy, negotiation strategy and agreement creation strategy need to be implemented in a domain-specific way for each SLA. The following sections describe how this is done in the WSAG4J framework.
A template creation strategy returns exactly one agreement template that is uniquely identified by its name and id. For convenience the context element of the template should also specify the name and id of this template. When an offer is created on the base of such a template it already references the original template. As mentioned earlier, this is required by the WSAG4J server in order to lookup the original template and the corresponding server action for an offer.
A template creation strategy implements the IGetTemplateAction interface. For convenience the WSAG4J framework provides an abstract base implementation of this interface with the AbstractGetTemplateAction class.
Moreover, WSAG4J supports the dynamic creation agreement templates using the Velocity template language. It is possible to design templates as XML files that include specific macros in order to dynamically generate for example service description terms or creation constraints. This template creation strategy is implemented by the VelocityAgreementTemplateAction class. This is the WSAG4J default implementation of a template creation strategy. For more information on how to create dynamic agreement templates using this strategy refer to the guide to create templates.
For each factory action a corresponding agreement creation strategy must be configured. This strategy is invoked for valid agreement offers that are based on the agreement template generated by this factory action. Before the agreement creation strategy is invoked, the WSAG4J server validates the incoming offer against the creation constraints defined in the corresponding template. This prevents that a strategy is invoked for invalid offers. Valid offers must for example have a defined structure or values of specific elements must be in predefined value spaces.
An agreement creation strategy implements the ICreateAgreementAction interface. The WSAG4J framework provides an abstract base implementation this interface with the AbstractCreateAgreementAction class. Implementations should inherit from this class.
A negotiation strategy implements the interface INegotiationAction. There also exists an abstract base implementation of this interface with the AbstractNegotiationAction class.
Server actions are configured in the wsag4j engine configuration file. Each wsag4j engine configuration file configures one agreement factory instance that is deployed in a WSAG4J server. The wsag4j engine configuration files are specified in the WSAG4JEngineInstances section of the global WSAG4J server configuration that is located in the /WEB-INF/classes/wsrf-engine.config file.
It is possible to configure multiple server actions for one agreement factory instance. Each server action results in one agreement template that is deployed in the agreement factory. The following sample shows a configuration of a particular server action.
<wsag4j-config:WSAG4JEngineConfiguration> <wsag4j-config:Validator> <wsag4j-config:SchemaImports> <wsag4j-config:SchemaFilename>/validator/xml.xsd</wsag4j-config:SchemaFilename> <wsag4j-config:SchemaFilename>/validator/XMLSchema.xml</wsag4j-config:SchemaFilename> <wsag4j-config:SchemaFilename>/validator/ws-addr.xsd</wsag4j-config:SchemaFilename> <wsag4j-config:SchemaFilename>/validator/bf-2.xsd</wsag4j-config:SchemaFilename> <wsag4j-config:SchemaFilename>/validator/ws-agreement-xsd-types.xsd</wsag4j-config:SchemaFilename> <wsag4j-config:SchemaFilename>/validator/jsdl.xsd-18.xsd</wsag4j-config:SchemaFilename> </wsag4j-config:SchemaImports> </wsag4j-config:Validator> <wsag4j-config:Action wsag4j-config:name="WSAG4J-SAMPLE-1"> <!-- Note that the implementation class elements should not include line breaks. --> <wsag4j-config:GetTemplateConfiguration> <wsag4j-config:ImplementationClass> org.ogf.graap.wsag.server.actions.impl.VelocityAgreementTemplateAction </wsag4j-config:ImplementationClass> <wsag4j-config:FileTemplateConfiguration> <wsag4j-config:Filename>/samples/template-1.xml.vm</wsag4j-config:Filename> </wsag4j-config:FileTemplateConfiguration> </wsag4j-config:GetTemplateConfiguration> <wsag4j-config:CreateAgreementConfiguration> <wsag4j-config:ImplementationClass> org.ogf.graap.wsag.samples.Sample1CreateAgreementAction </wsag4j-config:ImplementationClass> </wsag4j-config:CreateAgreementConfiguration> <wsag4j-config:NegotiationConfiguration> <wsag4j-config:ImplementationClass> org.ogf.graap.wsag.samples.Sample1NegotiateAgreementAction </wsag4j-config:ImplementationClass> </wsag4j-config:NegotiationConfiguration> </wsag4j-config:Action> </wsag4j-config:WSAG4JEngineConfiguration>
As mentioned before, implementations of an agreement creation strategy should inherit from AbstractCreateAgreementAction. This class already implements the required methods to handle wsag4j configuration data. Implementations therefore only need to implement two methods: initialize() and createAgreement(AgreementOffer).
public class ExampleCreateAgreementAction extends AbstractCreateAgreementAction { /** * The createAgreement() method is invoked when an offer was received that is based on the template * associated with this action. Since the structure of the template (and therefore the structure of the * offer) is known, we can simply access and the process offer content. * * The structure and the content of the offer can be restricted by defining Creation Constraints in the * agreement template. * * {@inheritDoc} */ public Agreement createAgreement( AgreementOffer offer ) throws AgreementFactoryException { // // This action is configured for a template that contains one // service description term that describes a computational service. // First we get the service description term. // ServiceDescriptionTermType sdt = offer.getTerms().getAll().getServiceDescriptionTermArray( 0 ); // // Now select the service description from the service description term. // This particular service description term contains a JSDL job definition document // of the type JobDefinitionType. We select the document and cast it to the // appropriate type. // JobDefinitionType job = (JobDefinitionType) sdt.selectChildren( JobDefinitionDocument.type.getDocumentElementName() )[0]; // // Now we can access the properties of the job ... // job.getJobDescription().getResources().getTotalResourceCount(); job.getJobDescription().getResources().getIndividualCPUCount(); job.getJobDescription().getResources().getTotalPhysicalMemory(); // // ... and instantiate a service. // ExampleService service = new ExampleService( job ); service.start(); // // Finally we create a new agreement instance based on the received offer. // The agreement properties are automatically initialized based on the offer. // For each service description term (guarantee term) a corresponding service // term state (guarantee term state is initialized.) // ExampleAgreement agreement = new ExampleAgreement( offer ); agreement.setService( service ); return agreement; } /** * This method is invoked when the action is initialized. The initialization process takes place when the * WSAG4J server is started. * * {@inheritDoc} */ public void initialize() throws ActionInitializationException { // // add implementation specific code here // } }
The initialize() method is invoked by the WSAG4J engine when a server factory action is instantiated. This method is also called for each strategy configured for a server actions. Within this method, implementations can do additional initialization, e.g. based on the configuration data provided in the wsag4j-engine.config.
The createAgreement() method is called, when the agreement factory receives a createAgreement() message with an offer that refers to the agreement template generated by this server action.