initial commit

author: Andreas Fitzek <andreas.fitzek@iaik.tugraz.at> 2015-11-03 14:38:34 +0100
committer: Andreas Fitzek <andreas.fitzek@iaik.tugraz.at> 2015-11-03 14:38:34 +0100
commit: 0872d2d8a64fd701776b272f49222428d8def07f (patch)
tree: 0954a523ad2cc7ad615dbbae5282dd56497e4c6e /moaSig/moa-sig-lib/src/main/javadoc/overview.html
parent: e635718b8d6a12e4e80207c8bdf30b02eed3f2ab (diff)
download: moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.tar.gz
moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.tar.bz2
moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.zip
1 files changed, 155 insertions, 0 deletions
diff --git a/moaSig/moa-sig-lib/src/main/javadoc/overview.html b/moaSig/moa-sig-lib/src/main/javadoc/overview.html
new file mode 100644
index 0000000..9b17bbf
--- /dev/null
+++ b/moaSig/moa-sig-lib/src/main/javadoc/overview.html
@@ -0,0 +1,155 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+</head>
+<body bgcolor="white">
+
+MOA SP/SS API documentation overview.
+
+
+<h2>Using the MOA SP/SS API</h2>
+
+<h3>Invoking the services</h3>
+In general, invoking the MOA SP/SS API involves the following steps:
+<ol>
+<li>Set the <code>moa.spss.server.configuration</code> 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).</li>
+<li>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 <code>getInstance()</code> method.</li>
+<li>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.</li>
+<li>Use the <code>create...</code> methods of the <code>SPSSFactory</code> 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.
+</li>
+<li>Call one of the service methods: 
+{@link at.gv.egovernment.moa.spss.api.SignatureCreationService#createXMLSignature(at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureRequest) <code>createXMLSignature()</code>},
+{@link at.gv.egovernment.moa.spss.api.SignatureVerificationService#verifyCMSSignature(at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureRequest) <code>verifyCMSSignature()</code>} or
+{@link at.gv.egovernment.moa.spss.api.SignatureVerificationService#verifyXMLSignature(at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureRequest) <code>verifyXMLSignature()</code>}.
+</li>
+<li>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 <code>CreateXMLSignatureResponse</code>.
+</ol>
+
+<h3>Creating MOA SP/SS API objects</h3>
+<p>
+Invoking the MOA SP/SS API <code>Service</code> classes involves creating
+a <code>Request</code> object using the {@link at.gv.egovernment.moa.spss.api.SPSSFactory SPSSFactory}.
+Object creation using the <code>SPSSFactory</code> is always bottom-up, meaning 
+that in order to create an object all of its components must have been created
+before.
+</p>
+<p>
+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 <code>xsd:choice</code> components:
+<ul>
+<li>The various <code>Profile</code> classes have subclasses called 
+<code>ProfileID</code> and <code>ProfileExplicit</code> 
+(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.</li>
+<li>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.</li>
+</ul>
+
+</p>
+<p>
+For clarity, the MOA SP/SS API classes have been organized in several packages
+listed in the following table:
+</p>
+
+<table border=1 cellspacing=0 cellpadding=5>
+<tr>
+  <td>Package</td><td>Purpose</td>
+</tr>
+<tr>
+  <td>{@link at.gv.egovernment.moa.spss.api.xmlsign}</td>
+  <td>Components of the {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureRequest} and 
+  {@link at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureResponse}</td>
+</tr>
+<tr>
+  <td>{@link at.gv.egovernment.moa.spss.api.cmsverify}</td>
+  <td>Components of the
+  {@link at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureRequest} and
+  {@link at.gv.egovernment.moa.spss.api.cmsverify.VerifyCMSSignatureResponse}</td>
+</tr>
+<tr>
+  <td>{@link at.gv.egovernment.moa.spss.api.xmlverify}</td>
+  <td>Components of the
+  {@link at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureRequest} and
+  {@link at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureResponse}</td>
+</tr>
+<tr>
+  <td>{@link at.gv.egovernment.moa.spss.api.common}</td>
+  <td>Common components used across the classes of the above packages</td>
+</tr>
+</table>
+
+<h3>Converting MOA SP/SS API objects to and from DOM trees</h3>
+The package {@link at.gv.egovernment.moa.spss.api.xmlbind} contains helper
+classes to:
+<ul>
+<li>Parse a DOM tree containing a <code>CreateXMLSignatureRequest</code>,
+<code>VerifyCMSSignatureRequest</code> or  
+<code>VerifyCMSSignatureRequest</code> into its respective MOA SP/SS API object 
+representation. For example, to parse a <code>CreateXMLSignatureRequest</code>
+DOM tree, the {@link at.gv.egovernment.moa.spss.api.xmlbind.CreateXMLSignatureRequestParser#parse(org.w3c.dom.Element) CreateXMLSignatureRequestParser.parse()} 
+method can be used. <br />
+<b>Note:</b> The DOM tree of the request must be derived from a schema valid
+XML document. Otherwise, unexpected behaviour will almost certainly result.</li>
+<li>Build a <code>CreateXMLSignatureResponse</code>, 
+<code>VerifyCMSSignatureResponse</code> or a 
+<code>VerifyXMLSignatureResponse</code> DOM tree from the respective MOA SP/SS 
+API object. For example, to build a <code>VerifyXMLSignatureResponse</code>
+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.<br />
+<b>Note:</b>The serialized DOM tree will be schema valid.
+</li>
+</ul>
+The DOM trees can easily be read from and written to XML byte streams using
+the methods in the {@link at.gv.egovernment.moa.util.DOMUtils} class.
+<br />
+
+<h3>Utilities and Logging</h3>
+<p> 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.
+</p>
+
+<p>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.
+</p>
+
+<h3>Related Documentation</h3>
+
+See also the <a href="../moa_spss/sp-anwendung.htm#API">API example</a> in the 
+MOA SP/SS documentation.
+
+</body>
+</html>
+\ No newline at end of file
author	Andreas Fitzek <andreas.fitzek@iaik.tugraz.at>	2015-11-03 14:38:34 +0100
committer	Andreas Fitzek <andreas.fitzek@iaik.tugraz.at>	2015-11-03 14:38:34 +0100
commit	0872d2d8a64fd701776b272f49222428d8def07f (patch)
tree	0954a523ad2cc7ad615dbbae5282dd56497e4c6e /moaSig/moa-sig-lib/src/main/javadoc/overview.html
parent	e635718b8d6a12e4e80207c8bdf30b02eed3f2ab (diff)
download	moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.tar.gz moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.tar.bz2 moa-sig-0872d2d8a64fd701776b272f49222428d8def07f.zip