[Intersult] [Abraxas] ist ein Werkzeug zur Kommunikation mit [SOAP] und anderen Protokollen.

!!!Inhalt
[{TableOfContents numbered=true}]

!!!Bestandteile
[Abraxas] besteht im wesentlichen aus folgenden Bestandteilen:

* __Remote-Client:__ Werkzeug zum Aufruf von Remove-Services, meist [SOAP].
* __Remote-Service:__ Der Service kann auf jeden JEE-Konformen [Application Server] installiert (deployed) werden.
* __Stubs generieren:__ [Abraxas] enthält Methoden zum Generieren von Java-Klassen aus WSDL- oder XSD-Dateien, aus dem Dateisystem oder über Remote-Streaming (HTTP usw.) Bei den generierten Stubs handelt es sich um leichtgewichtige Pojos, die keinen Code enthalten (außer der spezifischen Service-Konfiguration).
* __Sicherheit:__ Es wird HTTPS inklusive NTLM und anderen Authentifizierungen unterstützt.
* __Maven-Support:__ Abraxas fügt sich nahtlos in den Build-Prozess ein. Generierte Stubs erscheinen als Quellcode und können bei der Entwicklung im Content-Assist direkt angezeigt werden.
* __Transport Extensions:__ Die eigentliche Kommunikations-Schicht ist Erweiterbar. Neben den mitgelieferten Protokollen SOAP und REST können weitere Protokolle hinzugefügt werden.
* __XML-Tools:__ [Abraxas] kann auch genutzt werden, um Java-Objekte nach XML zu konvertieren und umgekehrt. Es werden Pojos unklusive Arrays, Listen und Maps unterstützt. Zusätzlich existieren einige Annotationen mit denen die Umwandlung an spezielle Bedürfnisse angepasst werden kann.

!!!Was macht Abraxas?
ist das [Produkt|Intersult Produkte] der [Intersult] für den Umgang mit Remote-Verbindungen und -Services im Bereich XML und [Java]. [Abraxas] ist  ein jahrelang entwickeltes und erprobtes Produkt, auf das mehrere renommierte Unternehmen setzen, weil es eines der führenden XML- und SOAP-Werkzeuge darstellt.

Das XML-Paket kann unter [Maven 2/3|Maven] direkt aus dem [Intersult Maven Repository] bezogen werden. Für [Rechte|Rechtliches] und Einsatz in kommerziellen Anwendungen nehmen Sie bitte [Kontakt|Intersult] zu uns auf.

!!!Maven2/3
Die Bibliotheken können aus dem [Intersult Maven Repository] bezogen werden.

The __XML Tools__ are accessible using the following ids:

|group-id|com.intersult
|artifact-id|abraxas
|version|1.3-SNAPSHOT

The __Maven Plugin__ is accessible under:

|group-id|com.intersult
|artifact-id|abraxas-maven
|version|1.3-SNAPSHOT

The __Remote-Service__:

|group-id|com.intersult
|artifact-id|abraxas-service
|version|1.3-SNAPSHOT

!!Konfiguration
In der Maven-Definition wird festgelegt, wie Java-Klassen aus WSDL- oder XSD-Links generiert werden. Der Eintrag für eine WSDL folgt dem Aufbau:

{{{
    <build>
        ...
        <plugins>
            ...
            <plugin>
	        <groupId>com.intersult</groupId>
	        <artifactId>abraxas-maven</artifactId>
	        <version>1.3-SNAPSHOT</version>
	        <executions>
	            <execution>
		        <goals>
		            <goal>generate-ws</goal>
		        </goals>
			<configuration>
	                    <services>
			        <service>
			    	    ...
			    	</service>
			    </services>
			</configuration>
	            </execution>
		<executions>
	    </plugin>
	    ...
	</plugins>
	...
    </build>
}}}

Unter <service> werden ein oder mehrere Services generiert. Unterhalb können weiter Parameter angegeben werden, die das Generieren der Servies steuern:

||Parameter||Bedeutung
|outputPath|Ausgabepfad für die generierten Klassen, in der Regel etwas wie ${project.build.directory}/generated-sources/weather
|wsdl|URL zur WSDL, zum Beispiel file:/${basedir}/src/main/resources/globalweather.wsdl oder kann auch direkt auf HTTP gehen. Durch Protocol-Plugins können auch weitere URLStreamHandler verwendet werden.
|packageName|Der Name der zu generierenden Packages. Falls er nicht angegeben wird, wird er aus dem Target-Namespace aus der WSDL generiert.
|ports *|Liste der zu generierenden "Ports", falls der Wert nicht angegeben wird, werden alle WSDL-Ports generert. Beispiel <ports><port>GlobalWeatherSoap</port></ports>
|operations* |Zu generierende WSDL-Operations. Wird der Wert nicht angegeben, werden alle Operations generiert. Beispiel wäre <operations><operation>GetWeather</operation></operations>
|xmlConfig|Konfiguration der XML-Verarbeitung durch Abraxas-XML, wie unter dem Abschnitt XML-Konfiguration beschrieben ist.
|protocol|Zu verwendender URLStreamHandler für den WSDL-URL, zum Beispiel <protocol implementation="com.intersult.testing.ServletUnitProtocol">
|mappings|Hier können zusätzliche Mappings beim Erzeugen der Java-Klassen definiert werden. Dies ist ein sehr fortgeschrittenes Feature und für gewöhnlich nicht notwendig, da die generierten Klassen abgeleitet und im RemoteClient registriert werden können.

Bei der Angabe von Ports und Operations werden (momentan) trotzdem alle Klassen aus dem eingebetteten XSD-Schema generiert.

!!!XML-Generieren und Verarbeiten
Die Klasse com.intersult.xml.Xml ist der Einstiegspunkt für das Umwandeln von XML in Objekte (Unmarshalling) und Objekte in XML (Marshalling).

!!Anwendung
Es braucht sich um keine speziellen Objekte handeln, sogenannte Pojos (Plain Old Java Objects) sind ausreichend, also keine besondere Superklasse oder Interface notwendig.

Das Marshalling und Unmarshalling stellt ein Default-Verhalten zur Verfügung, das einen sehr weiten Bereich von denkbaren Java-Objekten abdeckt. Darüber hinaus besteht die Möglichkeit durch einige Annotations das Marshalling zu steuern.

!!Datentypen
Neben primitiven Datentypen und verschachtelten Typen serialisiert der Marshaller auch Arrays, Lists und Maps.

!!Beispiel für Unmarshalling
{{{
    String xml = "<java.lang.String>Test</java.lang.String>";
    String string = (String)Xml.unmarshall(xml);
    System.out.println(string);
}}}

__Erklärung:__ Die XML "Datei" wird direkt als String im Java-Code erzeugt und der lokalen Variablen xml zugewiesen. Danach wird mit die Methode ''marshall'' der Klasse com.intersult.xml.Xml aufgerufen, welche Strings, Streams und andere Quellen in Java-Objekte umwandelt (sog. Unmarshalling).

!!Beispiel für Marshalling und Unmarshalling
Der XmlMarshaller ist ein sehr flexibles Werkzeug, das über die Klasse com.intersult.xml.Xml angesprochen wird. Diese Klasse stellt statische Methoden für das Umwandeln von Java-Objekten in XML (marshal) und von XML in Java-Objekte (unmarshal) zur Verfügung. Die Klasse ist dafür ausgelegt, sehr einfach genutzt zu werden.

Folgendes Code-Beispiel zeigt einen Unmarshal-Marshal-Roundtrip:

{{{
    Foo objectInput = new Foo();
    objectInput.setValue("Test-Wert");
    String xml = Xml.marshall(objectInput);
    System.out.println(xml);
    Foo objectOutput = (Foo)Xml.unmarshall(xml);
    System.out.println(objectOutput.getValue());
}}}

Mit Foo.java:

{{{
public class Foo {
	private String value;

	public String getValue() {
		return value;
	}
	public void setValue(String value) {
		this.value = value;
	}
}
}}}

!!XML-Konfiguration
Die XmlConfig-Klasse wird verwendet, um das XML-Marshalling und -Unmarshalling zu steuern. Es stehen folgende Parameter zur Verfügung:

||Parameter||Default||Bedeutung
|validate|true|Damit kann das validieren gelesener XML-Dateien durch angegebene XSD- und DTD-Dateien abgeschaltet werden.
|writeEmpty|false|Legt fest, ob Null-Objekte geschrieben werden sollen.
|useDefault|false|Damit kann das Verarbeiten von Default-Annotationen eingeschaltet werden.
|writeId|false|Legt fest ob extra Attribute für IDs bei Arrays und Maps geschrieben werden sollen.
|encoding|UTF-8|Legt das Encoding fest.
|writeType|NONE|Legt fest ob Java-Class-Namen geschrieben werden sollen. Bei NONE werden nur die einfachen Namen der Java-Properties geschrieben, außer beim Wurzel-Element falls dies keine Name- oder Namespace-Annotation enthält. Bei DERIVATES werden Klassennamen geschrieben, falls das Attribut von der Definition abweicht, also abgeleitet ist. Bei ALL werden die Typnamen immer geschrieben.
|throwUnknown|true|Damit können Exceptions abgeschaltet werden, die erzeugt werden wenn Attribut- und Elementnamen nicht auf die Java-Klassen gemappt werden können.
|mapping|-|Mappings für das Marshalling/Unmarshalling
|classLoader|XmlUnmarshaller.class.getClassLoader()|ClassLoader zum Laden von Klassen.
|attributeHandlers|Interne Handler|Handler welche die XML-Attribute verarbeiten, wie Namespace-Includes.
|pretty|true|Damit kann das Formattieren des generierten XML-Codes abgeschaltet werden.
|formatMap|Interne Formate|Registrierung von Klassen zur Formatierung von speziellen Objekten.
|namespaceStack|-|Zugriff auf den NamespaceStack der XML-Verarbeitung
|processIncludes|true|Damit können Schema-Include-Anweisungen komplett abgeschaltet werden.
|absoluteIncludes|true|Damit können absolute URLs bei Schema-Includes ausgeschaltet werden.
|throwDuplicate|true|Damit können die Exceptions bei konourrierenden Array- und Map-Einträgen abgeschaltet werden.
|usePrefix|false|Legt fest, ob die SOAP-Message ein Namespace-Prefix bekommen soll.
|processEnum|true|Legt fest, ob Enums generiert werden sollen.
|throwFault|true|Möglichkeit zum Abschalten von Exceptions bei SOAP-Faults.
|serializable|false|Damit können alle generierten Klassen serialisierbar gemacht werden.
|handleIds|true|Legt fest, ob ID-Angaben in Arrays und Maps verarbeitet werden.
|autoCdata|true|Legt fest, ob bei Bedarf automatisch CDATA-Elemente generiert werden sollen.
|logging|false|Legt fest, ob die XML-Kommunikation mitgeloggt werden soll.
|annotations|true|Legt fest ob Annotations generiert werden sollen.
|proxy|Proxy.NO_PROXY|Zu verwendendes java.net.Proxy
|connectTimeout|-|Timeout für die TCP-Connection.
|readTimeout|-|Timeout für das Lesen von der TCP-Connection.
|collectNamespace|true|Legt fest ob beim Generieren von XML die Namespace-Definitionen zuerst gesammelt werden und auf Dokumentenebene ausgegeben werden. Das reduziert Namespace-Definitionen und verkürzt damit das generierte XML.
|unwrap|false|Auspacken von Response-Klassen. Kann zu Fehlern führen, wenn die SOAP-Response-Messages mehrere Elemente enthalten.
|transparentNtlm|true|Experimentelles Feature zum Unterbinden von transparenter NTLM-Authentifizierung, falls der Client auf Windows-Rechnern läuft.
|induceTypes|true|Legt fest, ob bei der Schema-Induktion Typen wie Integer oder Datum automatisch erkannt werden oder ob standardmäßig xsd:string verwendet wird.

!!!Web Service (SOAP)
Der Client-Generator für [SOAP]-Service verwendet intern den [Intersult Xsd-Generator], der auch eigenständig nutzbar ist. Damit ist es möglich, Remote-Aufrufe über Intra- und Internet abzuwickeln. Eine große Zahl von Services, die auf unterschiedlichsten Technologien (auch nicht-Java) basieren, verwenden [SOAP]. Damit steht eine sehr große Menge an Services und Providern zur Verfügung.

Um einen Web-Service auf [SOAP]-Basis anzusprechen, braucht man zunächst Java-Klassen, die die entsprechenden Daten übertragen. Diese werden aus der sogenannten WSDL (Web Service Description Language) generiert, die der [SOAP]-Service zur Verfügung stellt. Darin ist beschrieben, welche Methoden der Service anbietet und welche Objekte für die Kommunikation verwendet werden.

Die Generierung von Web Services aus WSDL-Dateien baut zum Teil auf der Generierung von XML-Schemata aus XSD-Dateien auf. Durch folgende Konfiguration kann ein Web Service Client generiert werden:

{{{
<project>
    ...
    <build>
        ...
        <plugins>
            ...
        	<plugin>
	            <groupId>com.intersult</groupId>
		    <artifactId>abraxas-maven</artifactId>
		    <version>1.3-SNAPSHOT</version>
		    <executions>
			<execution>
		            <goals>
				<goal>generate-ws</goal>
			    </goals>
			    <configuration>
				<services>
			    	    <service>
				        <outputPath>${project.build.directory}/generated/weather</outputPath>
				        <wsdl>http://www.webservicex.net/globalweather.asmx?WSDL</wsdl>
				        <packageName>net.webservicex.globalweather</packageName>
				    </service>
			        </services>
			    </configuration>
			</execution>
		    </executions>
	        </plugin>
	    ...
	</plugin>
	...
    </build>
    ...
</project>
}}}

Der Global Weather Service generiert einen Service, der durch folgenden Code ansprechbar ist:

{{{
    GlobalWeatherSoap soap = new GlobalWeatherSoap();
    GetWeatherResponse weather = soap.getWeather("nuernberg", "germany");
    System.out.println(weather.getGetWeatherResult());
}}}

!!!XML-Schema (XSD)
[Abraxas] kann [Java]-Dateien auch aus XSD-Dateien generieren. Dies kann oft nützlich sein, wenn die XML-Dateien zur Konfiguration benutzt werden (Also keine XML-Kommunikation über SOAP erfolgt).

Dies kann in der pom.xml dann so aussehen:

{{{
<plugin>
	<groupId>com.intersult</groupId>
	<artifactId>abraxas-maven</artifactId>
	<version>1.3-SNAPSHOT</version>
	<executions>
		<execution>
			<id>generate-schema</id>
			<goals>
				<goal>generate-schema</goal>
			</goals>
			<configuration>
				<schemas>
					<schema>
						<xsdPath>${project.build.directory}/generated/web</xsdPath>
						<xsd>http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd</xsd>
					</schema>
				</schemas>
			</configuration>
		</execution>
	</executions>
</plugin>
}}}

Das Beispiel zeigt, wie das XML-Schema der web.xml Version 2.5 über HTTP gestreamt wird und darauf Java-Klassen generiert. Dies kann eingesetzt werden, um Java-Klassen zu erzeugen mit der eine web.xml abgebildet werden könnte mit dem Zweck diese auszulesen oder zu generieren.

!!!Protokolle
[Abraxas] arbeitet mit URL-Connections, ist daher sehr verträglich und unterstützt damit bereits eine Grundzahl von Protokollen. Allesdings kann es sinnvoll sein, zusätzliche Protokolle zu verwenden, zum Beispiel wenn Code aus einer HttpUnit oder anderen Quellen generiert werden soll. Dies ist nützlich, wenn Tests für SOAP-Services geschrieben werden sollen.

!!Durch globale Factory
Es können beliebige Protokolle hinzugefügt werden, wenn diese [ProtocolFactory] unterstützen:

{{{
<plugin>
	<groupId>com.intersult</groupId>
	<artifactId>abraxas-maven</artifactId>
	<version>1.3-SNAPSHOT</version>
	<executions>
		<execution>
			<id>generate-ws</id>
			<goals>
				<goal>generate-ws</goal>
			</goals>
			<configuration>
				<protocols>
					<com.intersult.testing.httpunit.HttpUnitProtocol>
						<webXmlFile>${basedir}/src/main/webapp/WEB-INF/web.xml</webXmlFile>
						<translateProtocol>false</translateProtocol>
					</com.intersult.testing.httpunit.HttpUnitProtocol>
				</protocols>
				<services>
					<service>
						<outputPath>${project.build.directory}/generated/test</outputPath>
						<wsdl>unit://localhost/remote/HelloService?wsdl</wsdl>
						<packageName>com.intersult.hello</packageName>
						<xmlConfig>
                				    <unwrap>true</unwrap>
						</xmlConfig>
					</service>
				</services>
			</configuration>
		</execution>
	</executions>
	<dependencies>
		<dependency>
			<groupId>com.intersult</groupId>
			<artifactId>testing</artifactId>
			<version>1.0-SNAPSHOT</version>
		</dependency>
	</dependencies>
</plugin>
}}}

Das Artifact mit dem entsprechenden Protocol wird also als Dependency des [Abraxas] Plugin hinzugefügt. Damit sind die entsprechenden Klassen während der Ausführung des [Abraxas] Plugins im Classpath zugreifbar und können in der Konfiguration unter "protocols" hinzugefügt und selbst mit Parametern versehen werden.

!!Lokale Protokoll-Handler
Es ist nicht immer sinnvoll, Protokolle durch die [ProtocolFactory] systemweit zu registrieren. Daher können Protokoll-Handler in der pom.xml lokal verwendet werden:

{{{
	<service>
		<outputPath>${project.build.directory}/generated-sources/test</outputPath>
		<wsdl>unit://localhost/remote/HelloService?wsdl</wsdl>
		<packageName>com.intersult.hello</packageName>
		<xmlConfig>
			<unwrap>true</unwrap>
		</xmlConfig>
		<protocol implementation="com.intersult.testing.ServletUnitProtocol">
			<webXmlFile>${basedir}/src/main/webapp/WEB-INF/web.xml</webXmlFile>
		</protocol>
	</service>
}}}

Beim Aufruf kann der Handler ebenfalls lokal verwendet werden:

{{{
	ServletUnitProtocol protocol = new ServletUnitProtocol();
	URL serviceUrl = new URL(null, HelloService.SERVICE_URL, protocol);
	HelloService helloService = new HelloService(serviceUrl, Transport.SOAP);
}}}