re-arranged handbook project step1

git-svn-id: https://joinup.ec.europa.eu/svn/moa-idspss/trunk@980 d688527b-c9ab-4aba-bd8d-4036d912da1d

3 files changed, 451 insertions, 0 deletions

diff --git a/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTP.java b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTP.java
new file mode 100644
index 000000000..00ae94c11
--- /dev/null
+++ b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTP.java
@@ -0,0 +1,204 @@
+package at.gv.egovernment.moa.spss.handbook.clients.webservice;
+
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.util.Properties;
+import java.util.Vector;
+
+import javax.xml.namespace.QName;
+import javax.xml.parsers.DocumentBuilder;
+import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.rpc.Call;
+import javax.xml.rpc.Service;
+import javax.xml.rpc.ServiceFactory;
+
+import org.apache.axis.message.SOAPBodyElement;
+import org.apache.xml.serialize.OutputFormat;
+import org.apache.xml.serialize.XMLSerializer;
+import org.w3c.dom.Document;
+
+/**
+ * Diese Klasse implementiert einen einfachen Client für das MOA SP/SS Webservice mittels Apache Axis. Die
+ * Verbindung erfolgt ungesichert über HTTP.
+ */
+public class HTTP
+{
+  protected Properties props_;
+
+  /**
+   * Methode main.
+   * 
+   * Enthält den Beispielcode der nötig ist um von Java aus auf MOA-SPSS zugreifen zu können. Der Zugriff
+   * passiert über das AXIS-Framework. Die Verbindung erfolgt ungesichert über HTTP.
+   * 
+   * @param args <ul>
+   *             <li>
+   *             args[0] enthält entweder die Bezeichnung "sign" oder "verify" zur Kennzeichnung,
+   *             ob ein Signaturerstellungsrequest, oder ein Signaturprüfrequest gesendet werden soll.
+   *             </li>
+   *             <li>
+   *             args[1] enthält einen Verweis auf eine Property-Datei, die die nähere Konfiguration
+   *             für dieses Beispiel enthält. Der Verweis enthält entweder eine absolute oder eine
+   *             relative Pfadangabe, wobei eine relative Angabe als relativ zum Arbeitsverzeichnis der
+   *             Java VM interpretiert wird. Folgende Properties müssen in der Property-Datei vorhanden
+   *             sein: 
+   *             <ul>
+   *             <li>
+   *             <code>signServiceQName</code>: Name des Webservices, fix "SignatureCreation"
+   *             </li>
+   *             <li>
+   *             <code>signServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>signRequest</code>: Name des zu sendenden Signaturerstellungsrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceQName</code>: Name des Webservices, fix "SignatureVerification"
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>verifyRequest</code>: Name des zu sendenden Signaturprüfrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             </ul>
+   *             </li>
+   *             </ul>
+   */
+  public static void main(String[] args)
+  {
+    try
+    {
+      // Prüfen, ob Beispiel korrekt verwendet wird
+      checkArgs(args, "HTTP");
+      
+      // Initialisieren des Clients
+      HTTP httpClient = new HTTP(args);
+      
+      // Ausführen der Serviceabfrage
+      httpClient.execute(args[0]);
+    }
+    catch (Exception e)
+    {
+      e.printStackTrace();
+    }
+  }
+  
+  /** 
+   * Prüft, ob das Beispiel korrekt verwendet wird.
+   * 
+   * @param args Die Aufrufparameter für das Beispiel. Siehe {@link HTTP#main(String[])}.
+   * 
+   * @param exampleName Der Name dieses Beispiels, der im Hilfetext gedruckt wird.
+   */
+  protected static void checkArgs(String[] args, String exampleName)
+  {
+    if (args == null || args.length != 2 || (!"sign".equals(args[0]) && !"verify".equals(args[0])))
+    {
+      System.out.println("Verwendung: " + exampleName + " \"sign\"|\"verify\" Properties-Datei");
+    }
+  }
+  
+  /**
+   * Erzeugt den MOA Client. Es erfolgt die Auswertung der übergebenen Aufrufparameter.
+   * 
+   * @param args Die Aufrufparameter für das Beispiel. Siehe {@link HTTP#main(String[])}.
+   * 
+   * @throws Exception wenn der MOA Client mit den übergebenen Aufrufparametern nicht korrekt erzeugt
+   *         werden konnte. 
+   */
+  protected HTTP(String[] args) throws Exception
+  {
+    props_ = new Properties();
+    props_.load(new FileInputStream(args[1]));
+  }
+  
+  /**
+   * Führt die Abfrage beim MOA-Service aus.
+   * 
+   * @param mode Steuert, ob eine Signatur erstellt ("sign") oder geprüft ("verify") werden soll.
+   * 
+   * @throws Exception wenn dabei etwas schiegeht.
+   */
+  protected void execute(String mode) throws Exception
+  {
+    // Datei mit Request einlesen
+    FileInputStream inputStream = new FileInputStream(getProperty(mode + "Request"));
+
+    // Parser/DOMBuilder instanzieren
+    DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
+    factory.setNamespaceAware(true);
+    DocumentBuilder builder = factory.newDocumentBuilder();
+
+    // XML Datei in einen DOM-Baum umwandeln
+    Document xmlRequest = builder.parse(inputStream);
+
+    // AXIS-Server instanzieren
+    Service service = ServiceFactory.newInstance().createService(new QName(getProperty(mode + "ServiceQName")));
+
+    // Call öffnen
+    Call call = service.createCall();
+
+    // Neues BodyElement anlegen und mit dem DOM-Baum füllen
+    SOAPBodyElement body = new SOAPBodyElement(xmlRequest.getDocumentElement());
+    SOAPBodyElement[] params = new SOAPBodyElement[]
+    {
+      body
+    };
+
+    // Call mit Endpoint verknüpfen
+    call.setTargetEndpointAddress(getProperty(mode + "ServiceEndPoint"));
+
+    // Call auslösen und die Antworten speichern
+    System.out.println("Calling ...");
+    Vector responses = (Vector) call.invoke(params);
+
+    // Erstes Body Element auslesen
+    SOAPBodyElement response = (SOAPBodyElement) responses.get(0);
+
+    // Aus der Response den DOM-Baum lesen
+    Document root_response = response.getAsDocument();
+    System.out.println("Return ...");
+
+    // XML-Formatierung konfiguieren
+    OutputFormat format = new OutputFormat((Document) root_response);
+    format.setLineSeparator("\n");
+    format.setIndenting(false);
+    format.setPreserveSpace(true);
+    format.setOmitXMLDeclaration(false);
+    format.setEncoding("UTF-8");
+
+    // Ausgabe der Webservice-Antwort auf die Konsole
+    XMLSerializer conSerializer = new XMLSerializer(System.out, format);
+    conSerializer.serialize(root_response);
+
+    // Ausgabe der Webservice-Antwort in Datei
+    String responseFile = getProperty(mode + "Request").substring(0, getProperty(mode + "Request").lastIndexOf('.'))
+      + ".response.xml";
+    XMLSerializer fileSerializer = new XMLSerializer(new FileOutputStream(responseFile), format);
+    fileSerializer.serialize(root_response);
+  }
+  
+  /**
+   * Prüft ob die Property mit dem angegebenen Namen in den Konfigurations-Properties enthalten ist.
+   *  
+   * @param propName Name der zu untersuchenden Property.
+   * 
+   * @return den Wert der gesuchten Property.
+   * 
+   * @throws Exception wenn die gesuchte Property nicht vorhanden ist.
+   */
+  protected String getProperty(String propName) throws Exception
+  {
+    String propValue = props_.getProperty(propName);
+    if ((propValue == null) || "".equals(propValue.trim()))
+    {
+      throw new Exception("Property named \"" + propName + "\" does not exist.");
+    }
+    return propValue;
+  }
+}
\ No newline at end of file
diff --git a/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSClientAuth.java b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSClientAuth.java
new file mode 100644
index 000000000..ef509088a
--- /dev/null
+++ b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSClientAuth.java
@@ -0,0 +1,122 @@
+package at.gv.egovernment.moa.spss.handbook.clients.webservice;
+
+
+/**
+ * Diese Klasse implementiert einen einfachen Client für das MOA SP/SS Webservice mittels Apache Axis. Die
+ * Verbindung erfolgt gesichert über SSL, und zwar sowohl mit Server- und Clientauthentisierung.
+ */
+public class HTTPSClientAuth extends HTTPSServerAuth
+{
+  // JSSE Konstanten
+  public static final String KEYSTORE = "javax.net.ssl.keyStore";
+  public static final String KEYSTOREPASSWORD = "javax.net.ssl.keyStorePassword";
+  public static final String KEYSTORETYPE = "javax.net.ssl.keyStoreType";
+
+  /**
+   * Methode main.
+   * 
+   * Enthält den Beispielcode der nötig ist um von Java aus auf MOA-SPSS zugreifen zu können. Der Zugriff
+   * passiert über das AXIS-Framework. Die Verbindung erfolgt gesichert über SSL, und zwar sowohl mit 
+   * Server- und Clientauthentisierung.
+   * 
+   * @param args <ul>
+   *             <li>
+   *             args[0] enthält entweder die Bezeichnung "sign" oder "verify" zur Kennzeichnung,
+   *             ob ein Signaturerstellungsrequest, oder ein Signaturprüfrequest gesendet werden soll.
+   *             </li>
+   *             <li>
+   *             args[1] enthält einen Verweis auf eine Property-Datei, die die nähere Konfiguration
+   *             für dieses Beispiel enthält. Der Verweis enthält entweder eine absolute oder eine
+   *             relative Pfadangabe, wobei eine relative Angabe als relativ zum Arbeitsverzeichnis der
+   *             Java VM interpretiert wird. Folgende Properties müssen in der Properties-Datei vorhanden
+   *             sein: 
+   *             <ul>
+   *             <li>
+   *             <code>signServiceQName</code>: Name des Webservices, fix "SignatureCreation"
+   *             </li>
+   *             <li>
+   *             <code>signServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>signRequest</code>: Name des zu sendenden Signaturerstellungsrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceQName</code>: Name des Webservices, fix "SignatureVerification"
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>verifyRequest</code>: Name des zu sendenden Signaturprüfrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             <li>
+   *             <code>ssl.truststore.type</code>: Typ des JSSE-Truststores (entweder "JKS" für einen
+   *             Java Key Store oder "PKCS12" für eine PKCS#12-Datei).
+   *             </li>
+   *             <li><code>ssl.truststore.type</code>: Relativer oder absoluter Pfad zum JSSE-Truststore.
+   *             Ein relativer Pfad wird relativ zum Arbeitsverzeichnis der Java VM interpretiert).
+   *             </li>
+   *             <li><code>ssl.truststore.pwd</code>: Passwort für den JSSE-Truststore.
+   *             </li>
+   *             <li>
+   *             <code>ssl.keystore.type</code>: Typ des JSSE-Keystores (entweder "JKS" für einen
+   *             Java Key Store oder "PKCS12" für eine PKCS#12-Datei).
+   *             </li>
+   *             <li><code>ssl.keystore.type</code>: Relativer oder absoluter Pfad zum JSSE-Keystore.
+   *             Ein relativer Pfad wird relativ zum Arbeitsverzeichnis der Java VM interpretiert).
+   *             </li>
+   *             <li><code>ssl.keystore.pwd</code>: Passwort für den JSSE-Keystore.
+   *             </li>
+   *             </ul>
+   *             </li>
+   *             </ul>
+   */
+  public static void main(String[] args)
+  {
+    try
+    {
+      // Prüfen, ob Beispiel korrekt verwendet wird
+      checkArgs(args, "HTTP");
+      
+      // Initialisieren des Clients
+      HTTPSClientAuth httpClient = new HTTPSClientAuth(args);
+      
+      // Ausführen der Serviceabfrage
+      httpClient.execute(args[0]);
+    }
+    catch (Exception e)
+    {
+      e.printStackTrace();
+    }
+  }
+  
+  /**
+   * Erzeugt den MOA Client. Es erfolgt die Auswertung der übergebenen Aufrufparameter.
+   * 
+   * @param args Die Aufrufparameter für das Beispiel. Siehe {@link HTTPSClientAuth#main(String[])}.
+   * 
+   * @throws Exception wenn der MOA Client mit den übergebenen Aufrufparametern nicht korrekt erzeugt
+   *         werden konnte. 
+   */
+  protected HTTPSClientAuth(String[] args) throws Exception
+  {
+    super(args);
+  }
+  
+  /**
+   * Konfiguriert JSSE für eine SSL-Verbindung mit Client- und Serverauthentisierung.
+   */
+  protected void configureSSL() throws Exception
+  {
+    super.configureSSL();
+    
+    // Konfiguriere Key-Store (enthält privaten Schlüssel und Zertifikat des Clients)
+    System.setProperty(KEYSTORETYPE, getProperty("ssl.keystore.type"));
+    System.setProperty(KEYSTORE, getProperty("ssl.keystore.loc"));
+    System.setProperty(KEYSTOREPASSWORD, getProperty("ssl.keystore.pwd"));
+  }
+}
\ No newline at end of file
diff --git a/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java
new file mode 100644
index 000000000..712c9dbe7
--- /dev/null
+++ b/spss/handbook/clients/webservice/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java
@@ -0,0 +1,125 @@
+package at.gv.egovernment.moa.spss.handbook.clients.webservice;
+
+import java.security.Security;
+
+import com.sun.net.ssl.internal.ssl.Provider;
+
+/**
+ * Diese Klasse implementiert einen einfachen Client für das MOA SP/SS Webservice mittels Apache Axis. Die
+ * Verbindung erfolgt gesichert über SSL, und zwar nur mit Serverauthentisierung.
+ */
+public class HTTPSServerAuth extends HTTP
+{
+  // JSSE Konstanten
+  public static final String HANDLER = "java.protocol.handler.pkgs";
+  public static final String TRUSTSTORE = "javax.net.ssl.trustStore";
+  public static final String TRUSTSTOREPASSWORD = "javax.net.ssl.trustStorePassword";
+  public static final String TRUSTSTORETYPE = "javax.net.ssl.trustStoreType";
+
+  /**
+   * Methode main.
+   * 
+   * Enthält den Beispielcode der nötig ist um von Java aus auf MOA-SPSS zugreifen zu können. Der Zugriff
+   * passiert über das AXIS-Framework. Die Verbindung erfolgt gesichert über SSL, und zwar nur mit 
+   * Serverauthentisierung.
+   * 
+   * @param args <ul>
+   *             <li>
+   *             args[0] enthält entweder die Bezeichnung "sign" oder "verify" zur Kennzeichnung,
+   *             ob ein Signaturerstellungsrequest, oder ein Signaturprüfrequest gesendet werden soll.
+   *             </li>
+   *             <li>
+   *             args[1] enthält einen Verweis auf eine Property-Datei, die die nähere Konfiguration
+   *             für dieses Beispiel enthält. Der Verweis enthält entweder eine absolute oder eine
+   *             relative Pfadangabe, wobei eine relative Angabe als relativ zum Arbeitsverzeichnis der
+   *             Java VM interpretiert wird. Folgende Properties müssen in der Properties-Datei vorhanden
+   *             sein: 
+   *             <ul>
+   *             <li>
+   *             <code>signServiceQName</code>: Name des Webservices, fix "SignatureCreation"
+   *             </li>
+   *             <li>
+   *             <code>signServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>signRequest</code>: Name des zu sendenden Signaturerstellungsrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceQName</code>: Name des Webservices, fix "SignatureVerification"
+   *             </li>
+   *             <li>
+   *             <code>verifyServiceEndPoint</code>: Zugangspunkt des Webservices (URL)
+   *             </li>
+   *             <li>
+   *             <code>verifyRequest</code>: Name des zu sendenden Signaturprüfrequests (entweder
+   *             absolute oder relative Pfadangabe; eine relative Pfadangabe wird relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert)
+   *             </li>
+   *             <li>
+   *             <code>ssl.truststore.type</code>: Typ des JSSE-Truststores (entweder "JKS" für einen
+   *             Java Key Store oder "PKCS12" für eine PKCS#12-Datei).
+   *             </li>
+   *             <li><code>ssl.truststore.type</code>: Relativer oder absoluter Pfad zum JSSE-Truststore.
+   *             Ein relativer Pfad wird relativ zum Arbeitsverzeichnis der Java VM interpretiert).
+   *             </li>
+   *             <li><code>ssl.truststore.pwd</code>: Passwort für den JSSE-Truststore.
+   *             </li>
+   *             </ul>
+   *             </li>
+   *             </ul>
+   */
+  public static void main(String[] args)
+  {
+    try
+    {
+      // Prüfen, ob Beispiel korrekt verwendet wird
+      checkArgs(args, "HTTP");
+      
+      // Initialisieren des Clients
+      HTTPSServerAuth httpClient = new HTTPSServerAuth(args);
+      
+      // Ausführen der Serviceabfrage
+      httpClient.execute(args[0]);
+    }
+    catch (Exception e)
+    {
+      e.printStackTrace();
+    }
+  }
+  
+  /**
+   * Erzeugt den MOA Client. Es erfolgt die Auswertung der übergebenen Aufrufparameter.
+   * 
+   * @param args Die Aufrufparameter für das Beispiel. Siehe {@link HTTPSServerAuth#main(String[])}.
+   * 
+   * @throws Exception wenn der MOA Client mit den übergebenen Aufrufparametern nicht korrekt erzeugt
+   *         werden konnte. 
+   */
+  protected HTTPSServerAuth(String[] args) throws Exception
+  {
+    super(args);
+    configureSSL();
+  }
+  
+  /**
+   * Konfiguriert JSSE für eine SSL-Verbindung mit Serverauthentisierung.
+   * 
+   * @throws Exception wenn die Konfiguration von JSSE fehlschlägt.
+   */
+  protected void configureSSL() throws Exception
+  {
+    // Aktivieren Sie die nächste Zeile für detailliertes Logging des SSL-Verbindungsaufbaus
+    // System.setProperty("javax.net.debug", "all");
+    
+    // Setzen des korrekten Protokoll-Handlers für https
+    Security.addProvider(new Provider());
+    System.setProperty(HANDLER, "com.sun.net.ssl.internal.www.protocol");
+
+    // Konfiguriere Trust-Store (enthält SSL-Zertifikat des MOA Services, dem vertraut wird)
+    System.setProperty(TRUSTSTORETYPE, getProperty("ssl.truststore.type"));
+    System.setProperty(TRUSTSTORE, getProperty("ssl.truststore.loc"));
+    System.setProperty(TRUSTSTOREPASSWORD, getProperty("ssl.truststore.pwd"));
+  }
+}
\ No newline at end of file