Using the MOA SP/SS API

Invoking the services

1. Set the moa.spss.server.configuration system property to point to the main MOA SP/SS configuration file. This needs to be done only once per JVM instance. You may also call {@link at.gv.egovernment.moa.spss.api.Configurator#init} at this point to pre-initialize MOA SP/SS (if not, it is done automatically upon service invocation).
2. Create an instance of the service to be used ({@link at.gv.egovernment.moa.spss.api.SignatureCreationService} or {@link at.gv.egovernment.moa.spss.api.SignatureVerificationService}), via its getInstance() method.
3. Create an instance of the {@link at.gv.egovernment.moa.spss.api.SPSSFactory}, via its {@link at.gv.egovernment.moa.spss.api.SPSSFactory#getInstance} method.
4. Use the create... methods of the SPSSFactory to create the desired {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureRequest}, {@link at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureRequest} or {@link at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureRequest} object.
5. Call one of the service methods: {@link at.gv.egovernment.moa.spss.api.SignatureCreationService#createXMLSignature(at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureRequest) createXMLSignature()}, {@link at.gv.egovernment.moa.spss.api.SignatureVerificationService#verifyCMSSignature(at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureRequest) verifyCMSSignature()} or {@link at.gv.egovernment.moa.spss.api.SignatureVerificationService#verifyXMLSignature(at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureRequest) verifyXMLSignature()}.
6. Analyze the result of the service call, given as a {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureResponse}, {@link at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureResponse} or {@link at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureResponse}. In case of an error, a {@link at.gv.egovernment.moa.spss.MOAException} is thrown by the service. Please be aware that errors during signature creation are reported as part of a CreateXMLSignatureResponse.

Creating MOA SP/SS API objects

Invoking the MOA SP/SS API Service classes involves creating a Request object using the {@link at.gv.egovernment.moa.spss.api.SPSSFactory SPSSFactory}. Object creation using the SPSSFactory is always bottom-up, meaning that in order to create an object all of its components must have been created before.

The names of the MOA SP/SS API classes have been chosen to correspond to the MOA SP/SS schema elements. The structure of the classes (i.e., their fields) also corresponds to the structure of the respective MOA SP/SS schema elements. However, a few classes escape this naming convention, mainly because the corresponding schema elements contain xsd:choice components:

• The various Profile classes have subclasses called ProfileID and ProfileExplicit (e.g., {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateTransformsInfoProfileID} and {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateTransformsInfoProfileExplicit}), so that the profile can be given either as an ID (which is to be resolved from the MOA SP/SS configuration) or explicitly.
• The classes {@link at.gv.egovernment.moa.spss.api.common.Content}, {@link at.gv.egovernment.moa.spss.api.cmsverify.CMSContent} and {@link at.gv.egovernment.moa.spss.api.xmlverify.TransformParameter} have subclasses specifying the type of content they actually contain. E.g., {@link at.gv.egovernment.moa.spss.api.common.ContentBinary} will contain a byte stream.

For clarity, the MOA SP/SS API classes have been organized in several packages listed in the following table:

Converting MOA SP/SS API objects to and from DOM trees

• Parse a DOM tree containing a CreateXMLSignatureRequest, VerifyCMSSignatureRequest or VerifyCMSSignatureRequest into its respective MOA SP/SS API object representation. For example, to parse a CreateXMLSignatureRequest DOM tree, the {@link at.gv.egovernment.moa.spss.api.xmlbind.CreateXMLSignatureRequestParser#parse(org.w3c.dom.Element) CreateXMLSignatureRequestParser.parse()} method can be used.
  Note: The DOM tree of the request must be derived from a schema valid XML document. Otherwise, unexpected behaviour will almost certainly result.
• Build a CreateXMLSignatureResponse, VerifyCMSSignatureResponse or a VerifyXMLSignatureResponse DOM tree from the respective MOA SP/SS API object. For example, to build a VerifyXMLSignatureResponse DOM tree, the {@link at.gv.egovernment.moa.spss.api.xmlbind.VerifyXMLSignatureResponseBuilder#build(at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureResponse) VerifyXMLSignatureResponseBuilder.build()} can be used.
  Note:The serialized DOM tree will be schema valid.

Utilities and Logging

The packages {@link at.gv.egovernment.moa.util} and {@link at.gv.egovernment.moa.spss.util} contain utility classes developed for the MOA SP/SS implementation. Since the classes contained in these packages are tailored towards the MOA SP/SS implementation, they are far from being complete in the sense of providing a utility class library. Therefore, they may or may not prove useful in the context of your application. Their interfaces may also change in future releases.

The package {@link at.gv.egovernment.moa.logging} contains classes for logging messages to the MOA SP/SS log hierarchy via the {@link at.gv.egovernment.moa.logging.Logger} class.

Related Documentation