Open-Xchange-SOAP-WSDL2JAVA: Difference between revisions

From Open-Xchange
No edit summary
(adjust for apache cxf)
Line 1: Line 1:
= How to provision Open-Xchange with Java and SOAP =
= How to provision Open-Xchange with Java and SOAP =


'''NOTE:''' please use <tt>/webservices</tt> instead of <tt>/servlet/axis2/services</tt> since the latter is deprecated and might be removed at any time.
== Overview ==


== Generating code with wsdl2java from Axis2 ==
We use [https://cxf.apache.org/ 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.
See the sample script below on how to generate stubs for the Open-Xchange provisioning APIs.
Line 9: Line 19:
  #!/bin/bash
  #!/bin/bash
   
   
  DEST=/home/someuser/workspace/axistest
  # 1. download apache-cxf tarball, extract it and "cd" into the directory
  AXISPATH=/home/someuser/axis2-1.5.6
#    (this script has been developed and verified with CXF versions 3.0 and 3.1)
  OXURL=http://localhost/servlet/axis2/services
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
  JAVA_HOME=/usr/lib/jvm/java-6-sun
# 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"
   
   
for class in Context User Group Resource; do
    $CXF_HOME/bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
        lname=$(echo $class | tr '[:upper:]' '[:lower:]')
        -p "http://soap.admin.openexchange.com=admin.soap.${lname}" \
        if [ -d $DEST/$lname ]; then
        -p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
                rm -rf $DEST/$lname
        -p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
        fi
        -p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
        $AXISPATH/bin/wsdl2java.sh -p ox${lname} -u -uw -sp -uri $OXURL/OX${class}Service?wsdl -o $DEST/$lname -ns2p http://soap.admin.openexchange.com=admin.soap.${lname},http://dataobjects.soap.admin.openexchange.com/xsd=admin.soap.${lname}.dataobjects,http://dataobjects.rmi.admin.openexchange.com/xsd=admin.rmi.${lname}.dataobjects,http://exceptions.rmi.admin.openexchange.com/xsd=admin.rmi.${lname}.exceptions,http://rmi.java/xsd=admin.rmi.${lname},http://io.java/xsd=admin.javaio.${lname}
        -p "http://rmi.java/xsd=${pname}.java.rmi" \
        -p "http://io.java/xsd=${pname}.java.io" \
        ${WSDLURL}/OX${class}Service?wsdl
  done
  done
 
rm -f $JAXBTMP


The script generates stubs for each of the Context, User, Group and Resource API within a separate directory.
The script generates stubs for each of the Context, User, Group and Resource API within a separate subdirectory of the $CODEBASE directory.


== Example Code ==
== Example Code ==


The code below lists all users within Context with ID 1:
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 java.rmi.RemoteException;
  import admin.soap.context.*;
  import oxuser.DatabaseUpdateExceptionException;
import com.openexchange.context.rmi.dataobjects.Credentials;
  import oxuser.DuplicateExtensionExceptionException;
  import com.openexchange.context.soap.dataobjects.Context;
  import oxuser.InvalidCredentialsExceptionException;
  import com.openexchange.context.soap.dataobjects.User;
  import oxuser.InvalidDataExceptionException;
  import oxuser.NoSuchContextExceptionException;
  import javax.xml.namespace.QName;
  import oxuser.NoSuchUserExceptionException;
  import java.io.IOException;
  import oxuser.OXUserServiceStub;
  import java.util.List;
  import oxuser.RemoteExceptionException;
  import oxuser.StorageExceptionException;
/*
  import admin.rmi.user.dataobjects.Credentials;
  * Example SOAP client for OXContextService
  import admin.soap.user.dataobjects.Context;
  *
  import admin.soap.user.dataobjects.User;
  * 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);
        try {
            Context ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds);
            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");
   
   
public class UserSOAPTest {
        try {
            User ret = userport.createByModuleAccessName(ctx, oxuser, "groupware_premium", creds);
            System.out.println("created user with id=" + ret.getId());
   
   
    public static void main(String[] args) throws RemoteException, InvalidDataExceptionException, StorageExceptionException, InvalidCredentialsExceptionException, DatabaseUpdateExceptionException, NoSuchContextExceptionException, RemoteExceptionException, NoSuchUserExceptionException, DuplicateExtensionExceptionException {
            System.out.println("hit enter to continue");
        OXUserServiceStub oxus = new OXUserServiceStub("http://10.20.30.176/servlet/axis2/services/OXUserService.OXUserServiceHttpSoap12Endpoint/");
            System.in.read();
   
   
        Context c = new Context();
            System.out.println("deleting created user again");
        c.setId(1);
            Delete del = new Delete();
        Credentials cred = new Credentials();
            del.setAuth(creds);
        cred.setLogin("oxadmin");
            del.setCtx(ctx);
        cred.setPassword("secret");
            del.setUser(oxuser);
        User allusers[] = oxus.listAll(c, cred);
            userport.delete(del);
        allusers = oxus.getMultipleData(c, allusers, cred);
        } catch (RemoteExceptionException e) {
        for(final User u : allusers) {
            e.printStackTrace();
            System.out.println("Login: " + u.getName() + ", Displayname: " + u.getDisplay_name());
        } 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();
        }
    }
}

Revision as of 10:13, 24 September 2015

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 -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 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);

        try {
            Context ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds);
            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();
        }
    }
}