How to create a WSAG4J agreement?

This is a step by step tutorial for new WSAG4J users. It describes the required steps to create a WSAG4J agreement using the programming language Java.

Basically there are 8 steps to perform:

  1. Identify yourself (Code example)

    Using WSAG4J you are supposed to identify yourself by the use the X.509 standard. You have to supply a keystore and a truststore file each.

  2. Give the address of your agreement WSAG4J server (Code example)

    To create an agreement you have to contact a WSAG4J server. Since you want to create a specific agreement you have to address a WSAG4J Web server that is in the position to handle your demand. In real business you have to clarify the address of the WSAG4J server in question in advance but here in this tutorial we will give you an example address.

    You have to supply the URL of a WSAG4J Web server.

  3. Identify your factory (Code example)

    A WSAG4J server is structured hierarchically. Factories are in charge of managing agreements. They may be identified by their name or their id. In real business you have to clarify the identity of the factory in question in advance but here in this tutorial we will give you an example factory name.

  4. Identify your template (Code example)

    An Agreement is based on a template. Templates are identified by their name or by their id and are managed by factories. In real business you have to clarify the identity of the template in question in advance but here in this tutorial we will give you an example template name.

  5. Adjust the template to your needs

The template invites you to fill in the specific dates for your agreement.

This is not the place to tell details about how to fill the template because this is service dependent. Ask the service provider for the details.

  1. Create an offer (Code example)

    To proceed you have to create an offer from your filled template.

  2. Create the agreement based on your offer (Code example)

    Now you can go for an agreement based on your offer.

  3. Terminate the agreement (Code example)

    Finally agreements should be terminated.

Code Examples

Identify yourself

Fill in the KeystoreProperties object with your credentials to receive a LoginContext object.

KeystoreProperties properties = new KeystoreProperties();
properties.setKeyStoreAlias("wsag4j-user");
properties.setPrivateKeyPassword("user@wsag4j");
    
properties.setKeyStoreType("JKS");
properties.setKeystoreFilename("/wsag4j-client-keystore.jks");
properties.setKeystorePassword("user@wsag4j");
        
properties.setTruststoreType("JKS");
properties.setTruststoreFilename("/wsag4j-client-keystore.jks");
properties.setTruststorePassword("user@wsag4j");
        
LoginContext loginContext = null;
try {
  loginContext = new KeystoreLoginContext(properties);
  loginContext.login();
} catch (LoginException e) {
  // failed
  System.out.println(">> creation of LoginContext failed: " + e);
  return;
}

Give the address of your agreement WSAG4J server

Create an EndpointReferenceType and there set the URL of your WSAG4J server.

EndpointReferenceType epr = EndpointReferenceType.Factory.newInstance();
epr.addNewAddress().setStringValue("http://127.0.0.1:8080/wsag4j-agreement-factory-1.0.3");

Create a AgreementFactoryRegistryClient object to get access to your agreement service.

AgreementFactoryRegistryClient registry = null;
try {
  registry = AgreementFactoryRegistryLocator.getFactoryRegistry(epr, loginContext);
} catch (Exception e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
}

Identify your factory

Get the list of all factories present in the registry (AgreementFactoryRegistryClient) and walk through the list looking for the factory in question, which will be assigned to the variable myFactory. Here we are looking for the factory that has an Id value of SAMPLE-INSTANCE-1.

AgreementFactoryClient[] factories = null;
AgreementFactoryClient myFactory   = null;
try {
  factories = registry.listAgreementFactories();
  for (AgreementFactoryClient afc : factories) {
    String facId = afc.getResourceId();
    if (facId.equals("SAMPLE-INSTANCE-1")) {
      // found
      myFactory = afc;
      break;
    }
  }
} catch (ResourceUnknownException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
} catch (ResourceUnavailableException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
}

Identify your template

Get the list of all templates present in the factory and walk through the list looking for the template in question, which will be assigned to the variable myTemplate. Here we are looking for the template named SAMPLE1.

AgreementTemplateType myTemplate = null;
try {
  AgreementTemplateType[] templates = myFactory.getTemplates();
  for (AgreementTemplateType att : templates) {
    for (AgreementTemplateType att : templates) {
      if (att.getName().equals("SAMPLE1")) {
        // found
        myTemplate = att;
        break;
      }
    }
  }
} catch (ResourceUnknownException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
} catch (ResourceUnavailableException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
}

Create an offer

Create an AgreementOffer object by calling the Constructor of the AgreementOfferType class giving the filled template as a parameter.

AgreementOffer offer = new AgreementOfferType(myTemplate);

Create the agreement based on your offer

Your factory will create the agreement for you based on the offer you submit.

AgreementClient agreement = null;
try {
  agreement = myFactory.createAgreement(offer);
} catch (AgreementFactoryException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
} catch (ResourceUnknownException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
} catch (ResourceUnavailableException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
}

Terminate the agreement

An agreement is terminated by a call to its terminate method.

try {
  agreement.terminate();
} catch (ResourceUnknownException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
} catch (ResourceUnavailableException e) {
  // failed
  System.out.println(">> failed: " + e);
  return;
}