Writing a program that logs in to BIRT iHub System
A login operation authenticates a user in BIRT iHub System. A login operation involves the following actions:
*An IDAPI application sends a Login request to BIRT iHub System.
*BIRT iHub System. sends a Login response to the IDAPI application.
A Login request receives a Login response message from BIRT iHub System. When a Login request succeeds, the Login response message contains an AuthId, which is an encrypted, authenticated token. When a Login request fails, BIRT iHub System sends a Login response containing an error code and a description of the error.
The authentication ID in the Login response message remains valid for the current session. Any subsequent request that the application sends to BIRT iHub System must include the authentication ID in the message.
Each login operation uses the com.actuate.schemas classes to encode and decode the SOAP request and response messages. The following sections describe the SOAP messages, classes, and program interactions necessary to implement a successful login operation.
The following application derives from the code in the BIRT iHub Integration Technology example applications for the Apache Axis 2 client. AcLogin class logs in to the BIRT iHub Systemto authenticate the user. If the login succeeds, the application prints a success message. If the login fails, the application prints a usage message.
import com.actuate.schemas.*;
 
public class AcLogin {
public static final String usage =
"Usage:\n"+
" java AcLogin [options]\n";
 
public static void main(String[ ] args) {
// set command line usage
Arguments.usage = usage;
 
// get command line arguments
Arguments arguments = new Arguments(args);
 
try {
// login to actuate server
AcController actuateControl = new
AcController(arguments.getURL( ));
actuateControl.setUsername(arguments.getUsername( ));
actuateControl.setPassword(arguments.getPassword( ));
if (actuateControl.login( )) {
System.out.println("Congratulations! You have
successfully logged into BIRT iHub System as
"+actuateControl.getUsername( ));
}
else {
System.out.println("Please try again.\n Usage:\n"+"
java AcLogin [options]\n");
}
}
catch (Exception e) {
e.printStackTrace( );
}
}
}
About the auxiliary classes provided by the sample application
In the code example, the application makes use of the auxiliary classes provided by the BIRT iHub Integration Technology installation for the Apache Axis 2 client. These classes perform tasks common to most applications. The source code files for the auxiliary classes are in the source directory. The auxiliary classes are sample application components and are not part of the com.actuate.schemas package generated by the Actuate WSDL document:
*Arguments is an auxiliary class that analyzes the command line arguments to detect predefined options and enumerate any additional arguments. The following list describes the predefined options that can be specified at the command line:
*serverURL
-h hostname specifies the SOAP endpoint. The default value, http://localhost:8000, is set in ActuateControl, another auxiliary class.
*username
-u username specifies the user name. The default value, Administrator, is set in ActuateControl.
*password
-p password specifies the password. The default value, "", is set in ActuateControl.
*volume
-v volume specifies the target volume name. Actuate Release 11 requires a volume name in the SOAP header. For earlier and later releases, this specification is optional.
*embeddedDownload
-e turns on the download embedded option. When downloading a file, you can specify whether to embed the content in the response or transmit the file as an attachment. The default value, False, is set in Arguments.
*printUsage
-? prints the usage statement.
*ActuateControl is a controller class that handles routine interactions between the client application and the underlying com.actuate.schemas classes. ActuateControl is a sample class. It is not a comprehensive implementation of all possible interactions. It implements the following essential parts of an IDAPI application:
*Instantiates an ActuateAPILocatorEx object that implements the required Actuate SOAP header extensions and sets the BIRT iHub URL, as shown in the following code example:
public ActuateControl( )
throws MalformedURLException,ServiceException {
actuateAPI = new ActuateAPILocatorEx( );
setActuateServerURL(actuateServerURL);
}
*Sets the endpoint for the proxy to the specified value of the Encyclopedia volume URL, as shown in the following code example:
public void setActuateServerURL(String serverURL)
throws MalformedURLException, ServiceException {
if ((proxy == null) ||
!serverURL.equals(actuateServerURL)) {
if (serverURL != null)
actuateServerURL = serverURL;
System.out.println("Setting server to " +
actuateServerURL);
proxy =
actuateAPI.getActuateSoapPort(
new java.net.URL(actuateServerURL));
}
}
*Creates and configures an Axis Call object that sends the SOAP message to an Encyclopedia volume, as shown in the following code example:
public org.apache.axis.client.Call createCall( ) throws
ServiceException {
org.apache.axis.client.Call call =
(org.apache.axis.client.Call)
actuateAPI.createCall( );
call.setTargetEndpointAddress(this.actuateServerURL);
return call;
}
*ActuateAPIEx interface extends com.actuate.schemas.ActuateAPI. This interface defines the necessary Actuate SOAP header extensions and the Call object that returns the SOAP header element. ActuateAPIEx defines the following Actuate SOAP header extensions:
*AuthId is a system-generated, encrypted String returned by BIRT iHub in a Login response. All requests, except a Login request, must have a valid AuthId in the SOAP header.
*Locale specifies the language, date, time, currency and other conventions for BIRT iHub to use when returning the data to a client.
*TargetVolume is an optional element that indicates the Encyclopedia volume that receives the request.
*ConnectionHandle supports keeping a connection open to view a persistent report. If ConnectionHandle is present in the SOAP header, the system routes subsequent viewing requests to the same View service that returned the ConnectionHandle.
*DelayFlush tells BIRT iHub to write updates to the disk when the value is False.
The following example shows the code for the ActuateAPIEx interface:
public interface ActuateAPIEx extends com.actuate.schemas.ActuateAPI {
public void setAuthId(java.lang.String authId);
public void setLocale(java.lang.String locale);
public void setTargetVolume(java.lang.String
targetVolume);
public void setConnectionHandle(java.lang.String
connectionHandle);
public void setDelayFlush(java.lang.Boolean delayFlush);
 
public java.lang.String getAuthId( );
public java.lang.String getLocale( );
public java.lang.String getTargetVolume( );
public java.lang.String getConnectionHandle( );
public java.lang.Boolean getDelayFlush( );
public org.apache.axis.client.Call getCall( );
}
*ActuateAPILocatorEx class extends com.actuate.schemas.ActuateAPILocator and implements the ActuateAPIEx interface. ActuateAPILocatorEx class creates the Call object and adds the Actuate SOAP header, as shown in the following code example:
public class ActuateAPILocatorEx
extends com.actuate.schemas.ActuateAPILocator
implements ActuateAPIEx {
…
public Call createCall( ) throws ServiceException {
call = (org.apache.axis.client.Call) super.createCall( );
if (null != authId)
call.addHeader(new SOAPHeaderElement(null, "AuthId",
authId));
if (null != locale)
call.addHeader(new SOAPHeaderElement(null, "Locale",
locale));
if (null != targetVolume)
call.addHeader(
new SOAPHeaderElement(null, "TargetVolume",
targetVolume));
if (null != connectionHandle)
call.addHeader(
new SOAPHeaderElement(
null,
"ConnectionHandle",
connectionHandle));
if (null != targetServer)
call.addHeader(
new SOAPHeaderElement(
null,
"TargetServer",
targetServer));
if (null != targetVolume)
call.addHeader(
new SOAPHeaderElement(null, "DelayFlush", delayFlush));
return call;
}
Logging in to BIRT iHub System
In the example application, AcLogin class calls ActuateControl.login( ) method. This method instantiates the com.actuate.schemas.Login object, then sets the values for username and password, as shown in the following code:
public boolean login( ) {
boolean success = true;
com.actuate.schemas.Login request =
new com.actuate.schemas.Login( );
request.setPassword(password);
request.setUser(username);
ActuateControl.login( ) sets the AuthId to null, then uses the proxy to make a remote procedure call to BIRT iHub. If successful, the call returns a reference to com.actuate.schemas.LoginResponse object, as shown in the following code example:
…
try {
actuateAPI.setAuthId(null);
com.actuate.schemas.LoginResponse response =
proxy.login(request);
authenticationId = response.getAuthId( );
actuateAPI.setAuthId(authenticationId);
}
catch (java.rmi.RemoteException e) {
// login failed
success = false;
}
return success;
}
In the code example, the LoginResponse object contains the authentication ID returned by BIRT iHub. The application uses LoginResponse.getAuthId( ) to access the value, then calls ActuateAPIEx.setAuthId( ) to make the value available to the application to embed in the header of a subsequent SOAP request message.