Open-Xchange-SOAP-WSDL2JAVA
How to provision Open-Xchange with Java and SOAP
Overview
We use Apache CXF as framework to implement SOAP with Java.
Apache CXF comes with a tool called wsdl2java which reads the WSDL published by an OX App Suite installation and generates classes which represent corresponding SOAP objects and method calls.
So the general procedure is:
- Setup OX including the SOAP admin interface
- Create classes with wsdl2java
- Use these classes in your Java code to make SOAP calls
Generating code with wsdl2java from Apache CXF
See the sample script below on how to generate stubs for the Open-Xchange provisioning APIs.
#!/bin/bash # 1. download apache-cxf tarball, extract it and "cd" into the directory # (this script has been developed and verified with CXF versions 3.0 and 3.1) # 2. change variables CODEBASE, JAVA_HOME and WSDLURL # 3. run this script "bash oxaas-wsdl2java" export JAVA_HOME="/usr/lib/jvm/java-1.7.0-openjdk-amd64" CODEBASE="./codebase" WSDLURL="http://192.168.101.84/webservices" CXF_HOME=/opt/apache-cxf-3.0.5 rm -rf $CODEBASE frontend=jaxws21 dbinding=jaxb JAXBTMP=/tmp/jaxb$$.xml rm -f $JAXBTMP cat<<EOF > $JAXBTMP <jaxb:bindings version="2.1" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <jaxb:globalBindings generateElementProperty="false"/> </jaxb:bindings> EOF for class in Context User Group Resource; do lname=$(echo $class | tr '[:upper:]' '[:lower:]') pname="com.openexchange.$lname" $CXF_HOME/bin/wsdl2java -encoding utf8 -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \ -p "http://soap.admin.openexchange.com=admin.soap.${lname}" \ -p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \ -p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \ -p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \ -p "http://rmi.java/xsd=${pname}.java.rmi" \ -p "http://io.java/xsd=${pname}.java.io" \ ${WSDLURL}/OX${class}Service?wsdl done rm -f $JAXBTMP
The script generates stubs for each of the Context, User, Group and Resource API within a separate subdirectory of the $CODEBASE directory.
Example Code
Building the example code given below either requires some build tool / IDE of your choice (whose configuration is out of scope of this article) or you can build and run the example code manually like
# clean up old stuff from previous run rm -rf codebase *.class # generate java classes and compile them ./ox-wsdl2java find codebase -name \*.java | xargs javac # compile and run sample program javac -cp codebase MyContextClientExample.java MyUserClientExample.java java -cp .:codebase MyContextClientExample java -cp .:codebase MyUserClientExample
Sample client code follows below.
MyContextClientExample.java shows createcontext, listcontext, deletecontext:
import admin.soap.context.*; import com.openexchange.context.rmi.dataobjects.Credentials; import com.openexchange.context.soap.dataobjects.Context; import com.openexchange.context.soap.dataobjects.User; import com.openexchange.context.soap.dataobjects.SchemaSelectStrategy; import javax.xml.namespace.QName; import java.io.IOException; import java.util.List; /* * Example SOAP client for OXContextService * * creates a context, calls listcontext, deletes the context again */ public class MyContextClientExample { private static final QName SERVICE_NAME = new QName("http://soap.admin.openexchange.com", "OXContextService"); public static void main(String[] args) { final String subadminname = "oxadminmaster"; final String subadminpw = "secret"; final String ctxname = "soapcontext"; Credentials creds = new Credentials(); Context ctx = new Context(); User oxadmin = new User(); OXContextService contextservice = new OXContextService(OXContextService.WSDL_LOCATION, SERVICE_NAME); OXContextServicePortType contextport = contextservice.getOXContextServiceHttpsEndpoint(); creds.setLogin(subadminname); creds.setPassword(subadminpw); ctx.setName(ctxname); ctx.setMaxQuota(10000l); ctx.setId(10001); final String adminEmail = "oxadmin@example.com"; final String ctxadmname = "oxadmin"; final String ctxadmpw = "secret"; oxadmin.setName(ctxadmname); oxadmin.setPassword(ctxadmpw); oxadmin.setDisplayName("OX Admin"); oxadmin.setSurName("OX"); oxadmin.setGivenName("Admin"); oxadmin.setPrimaryEmail(adminEmail); oxadmin.setEmail1(adminEmail); oxadmin.setDefaultSenderAddress(adminEmail); oxadmin.setLanguage("en_US"); oxadmin.setTimezone("Europe/Berlin"); CreateModuleAccessByName cmab = new CreateModuleAccessByName(); cmab.setAccessCombinationName("groupware_premium"); cmab.setAdminUser(oxadmin); cmab.setAuth(creds); cmab.setCtx(ctx); SchemaSelectStrategy strategy = new SchemaSelectStrategy(); strategy.setStrategy("automatic"); try { Context ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, strategy); System.out.println("created context with id=" + ret.getId()); System.out.println("existing contexts:"); List<Context> allctxs = contextport.listAll(creds); for (final Context c : allctxs) { System.out.println(c.getName() + " with id=" + c.getId()); } System.out.println("hit enter to continue"); System.in.read(); System.out.println("deleting created context again"); Delete del = new Delete(); del.setAuth(creds); del.setCtx(ctx); contextport.delete(del); } catch (RemoteExceptionException e) { e.printStackTrace(); } catch (StorageExceptionException e) { e.printStackTrace(); } catch (InvalidCredentialsExceptionException e) { e.printStackTrace(); } catch (InvalidDataExceptionException e) { e.printStackTrace(); } catch (ContextExistsExceptionException e) { e.printStackTrace(); } catch (NoSuchContextExceptionException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } catch (DatabaseUpdateExceptionException e) { e.printStackTrace(); } } }
MyUserClientExample.java shows createuser, deleteuser:
import admin.soap.user.*; import com.openexchange.user.rmi.dataobjects.Credentials; import com.openexchange.user.soap.dataobjects.Context; import com.openexchange.user.soap.dataobjects.User; import javax.xml.namespace.QName; import java.io.IOException; /* * Example SOAP client for OXUserService * * Create a user and delete it again * */ public class MyUserClientExample { private static final QName SERVICE_NAME = new QName("http://soap.admin.openexchange.com", "OXUserService"); public static void main(String[] args) { final String adminname = "oxadmin"; final String adminpw = "secret"; final int ctxid = 10001; Credentials creds = new Credentials(); Context ctx = new Context(); User oxuser = new User(); OXUserService userservice = new OXUserService(OXUserService.WSDL_LOCATION, SERVICE_NAME); OXUserServicePortType userport = userservice.getOXUserServiceHttpsEndpoint(); creds.setLogin(adminname); creds.setPassword(adminpw); ctx.setId(ctxid); oxuser.setName("oxuser1"); oxuser.setPassword("secret"); oxuser.setDisplayName("OX User 1"); oxuser.setSurName("OX"); oxuser.setGivenName("User 1"); oxuser.setPrimaryEmail("oxuser1@soapcontext"); oxuser.setEmail1("oxuser1@soapcontext"); oxuser.setDefaultSenderAddress("oxuser1@soapcontext"); oxuser.setImapLogin("oxuser1@soapcontext"); oxuser.setImapServer("localhost"); oxuser.setSmtpServer("localhost"); oxuser.setLanguage("en_US"); oxuser.setTimezone("Europe/Berlin"); try { User ret = userport.createByModuleAccessName(ctx, oxuser, "groupware_premium", creds); System.out.println("created user with id=" + ret.getId()); System.out.println("hit enter to continue"); System.in.read(); System.out.println("deleting created user again"); Delete del = new Delete(); del.setAuth(creds); del.setCtx(ctx); del.setUser(oxuser); userport.delete(del); } catch (RemoteExceptionException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } catch (DatabaseUpdateExceptionException e) { e.printStackTrace(); } catch (StorageExceptionException e) { e.printStackTrace(); } catch (InvalidCredentialsExceptionException e) { e.printStackTrace(); } catch (InvalidDataExceptionException e) { e.printStackTrace(); } catch (NoSuchContextExceptionException e) { e.printStackTrace(); } catch (NoSuchUserExceptionException e) { e.printStackTrace(); } } }
Finally sometimes it is required to not directly make a SOAP call, but to generate the request body separately. One example therefore are gatling performance tests, where we can make SOAP tests if we just generate the SOAP (=HTTP POST) bodies separately and make, from the gatling point of view, simple HTTP POST requests.
Full working code therefore can be found in our gatling git repo, see gatling for details. The relevant steps to create the SOAP body itself are given below. It is scala code; how to translate it to Java (if required) should be straightforward.
import admin.soap.context.{ CreateModuleAccessByName, CreateModuleAccessByNameResponse } import com.openexchange.context.rmi.dataobjects.Credentials import com.openexchange.context.soap.dataobjects.{Context, Database, User} import java.io.{ByteArrayInputStream, ByteArrayOutputStream} import javax.xml.bind.{JAXBContext, Marshaller, Unmarshaller} import javax.xml.parsers.DocumentBuilderFactory import javax.xml.soap.{MessageFactory, SOAPMessage} import org.w3c.dom.Document val creds: Credentials = new Credentials val ctx: Context = new Context val oxadmin: User = new User // fill relevant fields of the creds, ctx, oxadmin oxbjects val cmab: CreateModuleAccessByName = new CreateModuleAccessByName cmab.setAccessCombinationName("all") cmab.setAdminUser(oxadmin) cmab.setAuth(creds) cmab.setCtx(ctx) val jaxbContext: JAXBContext = JAXBContext.newInstance(classOf[CreateModuleAccessByName]) val jaxbMarshaller: Marshaller = jaxbContext.createMarshaller jaxbMarshaller.setProperty(Marshaller.JAXB_FRAGMENT, true) val document: Document = DocumentBuilderFactory.newInstance.newDocumentBuilder.newDocument jaxbMarshaller.marshal(cmab, document) val soapMessage: SOAPMessage = MessageFactory.newInstance.createMessage // optional cosmetic: change namespace from SOAP-ENV to soap to match other conventions soapMessage.getSOAPPart().getEnvelope().removeNamespaceDeclaration("SOAP-ENV") soapMessage.getSOAPPart().getEnvelope().addNamespaceDeclaration("soap", "http://www.w3.org/2001/12/soap-envelope") soapMessage.getSOAPPart().getEnvelope().setPrefix("soap") soapMessage.getSOAPHeader().setPrefix("soap") soapMessage.getSOAPBody().setPrefix("soap") // optional cosmetic end soapMessage.getSOAPBody.addDocument(document) val outputStream: ByteArrayOutputStream = new ByteArrayOutputStream(); soapMessage.writeTo(outputStream); val soapBody: String = outputStream.toString()