Using Eloqua WS API with Java - Series Introduction
This three part series we will walk through using the Eloqua WS API with Java and related technologies. The goal of the series is to show with the choice of a few simple examples the approach to working with the API to complete some simple tasks, along with making sure we avoid some problems that might occur.
The series will be broken down as follows
1. Basic setup and getting started
2. Simple API usage scenarios.
3. Working with emails and deployments
Part 1 - Basic Setup and Usage:
In this tutorial of working with the Eloqua WS API in Java we will utilize the Axis2 library and related modules along with Eclipse as the IDE.
Developer Pre-Requisites
We will begin by first making getting all the tools and technologies that are being used in this tutorial. Please ensure that you have all the right pieces downloaded and in place before we begin to avoid issues later in the tutorial.
Tools and technologies
The Java Web Service Client will be built using Apache Axis2 and Apache Rampart. To facilitate the development of the client the Eclipse IDE will be used along with a Axis2 specific Eclipse plug-in.
The samples that will be built shall be setup as simple Console applications to make it very easy to test them; the code, however, can be used in any deployment topology including web application.
Installation and setup
Download and install the latest Java SE 6 JDK.
Eclipse IDE for Java Developers ( Helios SR2 )
Download and install (extract) the Eclipse IDE on your computer. Please make note of the directory where you have installed it.
Note If you already have any other version of the Helios release that will work as well - we will install the required plug-in later.
Download and install the latest version of the Axis2/Java release, the Binary Distribution will be all that is needed. Follow instructions provided.
Download and extract the latest version of the Rampart module, the Binary Distribution will be all that is needed. Follow instructions provided.
Apache Rampart - Version 1.5.1
Code Generator Wizard - Eclipse Plug-in
Download and install the Code Generator Eclipse Plug-In for Axis2.
- Download the ZIP file for the plugin you want to install.
- Extract the content of the plugins folder in the ZIP archive into the dropins folder (i.e. do not create a plugins folder under dropins).
Note: Restart eclipse to ensure that the plug-in gets loaded successfully.
To ensure that the plug-in has successfully do the following:
1. Start Eclipse
2. Select File --> New --> Other
If Axis2 Wizards shows up as shown above then the plug-in is ready to use. If it does not show up please ensure that the jar file is in the correct location and restart Eclipse if necessary.
Getting Started
In this section we shall start with generating the WS Clients and then configure Axis2 to ensure that we are able to connect to the Eloqua WS API.
Before starting please make sure that the you valid credentials ( username / password ) for an Eloqua User that has been granted the API access.
Generate WS Clients
To generate the WS Client the first step is to create a new project in Eclipse.
File --> New --> Project --> Java Project
Name the project ( I chose EloquaWSClient )and click Finish
Right click on the new project and then select New --> Other--> Axis2 Code Generator
The client will be created from a WSDL so make the selection and click Next.
Enter the Eloqua Service URL https://secure.eloqua.com/API/1.2/Service.svc?wsdland click Next
Next select Custom as the Codegen option.
Change the package name of the client to something that does not contain _1._2
Select Generate Sync Style only and then click Next
First select to browse and select a project from the workspace and then click Browse and find the project you just created.
Check the option to add the Axis2 codegen jars
Check the option to add Axis2 libraries to the codegen result project. Once you click browse you will have to point to the location where the Axis2 libraries were installed. Click Check Libs to make sure the libraries are found.
Finally click Finish and the client code should be generated.
Configure Eclipse Project
Once the code has been generated the next step is to ensure that the Eclipse Project that was created will have the correct build path setup. First ensure that the source files for the clients are in the project src directory.
NOTE: Don't worry if it's all red - we will fix it next with the build path.
Next select the project and choose Build Path --> Configure Built Path
Next select the Libraries tab and choose to Add Jars... then from the lib folder select all the jar files and click OK
If project is already setup for Build Automatically just wait a few seconds and you will see all the compiler errors will be gone!
NOTE - If you have installed Apache Rampart correctly you will see at the very least the Rampart Jars.
If these are not present the following steps will have to be done:
Step 1. Open the folder in which Apache Rampart was installed and select all jar files in the lib directory.
Step 2. Copy these jar files into the lib folder of your eclipse project and then go through the Build Path steps to include these in the project as well.
Connecting to Eloqua WS API
First we will start with a simple console application to make sure that we can connect to the Eloqua WS API. To do so first we create a simple Java Class, select the project and choose to create a new class:
Next enter the name of the package and class and click Finish.
The content of this file will be
package com.eloqua.sample;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.log4j.BasicConfigurator;
import com.eloqua.secure.api.EloquaStub;
import com.eloqua.secure.api._1_2.ListAssetTypes;
public class WSConsoleClient {
public static void main(String[] args) throws Exception { // To debug the this line will set Log4J to use System.Out for a lot of messages. //BasicConfigurator.configure(); // Configure your username and password here. String company = " "; String username = " "; String password = " "; // Assuming that the conf directory has the Axis2 config file and Rampart is installed correctly. ConfigurationContext ctx = ConfigurationContextFactory.createConfigurationContextFromFileSystem("D:\\Apache\\axis2-1.5.4\\conf", null); EloquaStub stub = new EloquaStub(ctx,"https://secure.eloqua.com/API/1.2/Service.svc"); ServiceClient sc = stub._getServiceClient(); Options options = sc.getOptions(); sc.engageModule("rampart"); options.setUserName(company +"\\"+username); options.setPassword(password); String[] assetTypes = stub.listAssetTypes(new ListAssetTypes()).getListAssetTypesResult().getAssetTypes().getString(); System.out.println("Asset Types count : " + assetTypes.length); for ( String s : assetTypes) { System.out.println(" -> " + s); } }
}
Make sure of the following:
1. The login credentials are added correctly.
2. The location of the Apache Axis2 Configuration file is set correctly.
3. It is VERY important to ensure security works that Apache Rampart was correctly added; in particular the modules directory of your Apache Axis2 installation MUST have the rampart MAR file.
If this file is NOT present please go back and install Apache Rampart with the installation instructions.
Running the code
To run the sample simply select the file you just created and then select Run As --> Java Application
In the Console you should see the following output:
log4j:WARN No appenders could be found for logger (org.apache.axiom.om.util.StAXUtils).
log4j:WARN Please initialize the log4j system properly.
Asset Types count : 10
-> DataExport
-> DataImport
-> EmailHeader
-> EmailFooter
-> ContactGroup
-> CompanyGroup
-> ProspectGroup
-> Form
-> None
Congrats - you are now using the Eloqua WS API!
Next Steps
Having completed the steps above you should be able to now run all the other WS API calls by using the documentation provided.