Part 2. Developing BOE Java Web Applications using Eclipse

November 9, 2009 – 12:46 pm

In the previous article we looked at setting up Eclipse for developing Java web applications. In this article we’ll look at the additional configuration required for the development of Java web applications that use the BusinessObjects SDK.

Overview

This article covers the steps to configure Eclipse to use the BOE SDK and also walks through creating a simple web application to test the configuration. It doesn’t discuss the actual BOE SDK nor provide details of the API, furthermore it also understands that the reader is already adept at Java Web Development.

This article assumes you have BusinessObjects Enterprise XI3.1 installed locally. However you can use a remote installation of BOE on a separate server. In this case you should still install a JDK and Tomcat on your development workstation and then perform a web tier installation of BusinessObjects on your workstation. Instructions for this can be found in either the BusinessObjects Enterprise XI 3.1 Installation and Configuration Guide for Windows or the equivalent document for Unix. These documents can be downloaded from SAP Support.

Create a New Project

We can either create a new project or carry on using the project we created in part 1. If you are goin to carry on using the same project then skip to next section otherwise to create a new project,

1. Create a new Dynamic Web Project by right-clicking in the empty white space of the Package Explorer pane at the extreme left of the workbench,
2. Choose New, then Dynamic Web Project.
3. No further configuration is required so just click finish

Configuring your Project to reference the BOE SDK

First we need to configure our project to refer to the BOE JAR files that contain the SDK

1. Right click over your project and select Build Path > Configure Build Path
2. Select the libraries tab and click Add External JARs
3. Navigate to the BusinessObjects installation folder and then to the subfolder,

   [BOE_INSTALL]\common\4.0\java\lib

4. and select the following JAR files. Note, holding control key will allow you to select more than one at a time,

biplugins.jar
cecore.jar
celib.jar
ceplugins_core.jar
cesdk.jar
cesession.jar
logging.jar

5. Once added the Java Build Path should look like this.


Configuring the Java build path in the project's preferences

6. Click OK to close the dialog

If you expand Java Resources in the project explorer you’ll see the JAR files you’ve added. You’ll also see many other JAR files and these are JAR files that the original files we added depend on.

Note on BOE SDK Libraries

The set of libraries listed above is the minimum required to logon to BusinessObjects Enterprise. They will also provide all the BOE Administration functionality such as working with users, scheduling documents, moving or copying documents etc. If you need to write an application that creates or edits Crystal Reports or Web Intelligence documents or to make use of BOE Web Services then you will need to add further libraries. Refer to the BusinessObjects Developer Guider which can be found at the SAP BusinessObjects community for full details however below is a list of the libraries required for working with Web Intelligence and Crystal Reports.

For working with Web Intelligence reports add the following libraries

boconfig.jar
jtools.jar
rebean.common.jar
rebean.fc.jar
rebean.wi.jar
rebean.jar
wilog.jar

These will then add the dependent Libraries. If any aren’t added automatically then add manually

cdzlet.jar
xalan.jar
xercesImpl.jar
xml-apis.jar
xpp3.jar

For working with Crystal Reports add the following libraries from the Report Application Server Java SDK,

rasapp.jar
rascore.jar
reporttemplate.jar
serialization.jar

These don’t have any dependent JAR files.

Allowing Tomcat to Compile JSPs that use the BOE SDK

This is enough to allow us to write java classes such as Servlets. When we request Eclipse to compile a Java class that uses BOE SDK Eclipse knows how to reference the BOE SDK libraries and so it can compile the classes successfully. However when we write a JSP that uses BOE SDK then it is Tomcat that will compile the JSP and so we need to make sure that Tomcat can also reference the BOE SDK libraries. To do this we can instruct Eclipse to include the BOE SDK JAR files when compiling the web application and it does this by including them in the lib folder under WEB-INF.

To add the JAR files to the web application lib folder,

1. Right Click over the project in the project explorer and select Properties.
2. Select Java EE Module Dependencies in the left hand menu
3. The JAR files we added should be listed in the window. Click Select All to select all the JAR files and click Apply.


Configuring the module dependencies to allow Tomcat to compile JSPs that using the BOE SDK

4. Once done click OK to close the dialog.

That’s all the configuration required and we can now start developing web applications that use the BOE SDK. To ensure that all is working as expected we’ll next create a simple BOE logon / logoff application.

Creating a Simple BOE Logon Application

Here we’ll create a simple application that allows a user to logon to BusinessObjects Enterprise and then logoff again. The application will first display a logon screen where the user can enter the BOE server name, a username and a password. When they click logon the data is submitted to a JSP which will use this data to logon to BOE, display a success or failure message and a button to logout.

First let us create the logon form,

1. Right click over the project explorer and select New > HTML Page.
2. Name it “loginForm” and select your preferred template

You can edit the page using a plain text editor or using a visual editor. To open an editor right click over loginForm.html in the project explorer and select Open With and then select your preferred editor. You can also preview the page using Open With Web Browser.

3. Edit the web page and add the following login form,

<form action="login.jsp">
  Server: <input name="CMS" type="text" />
  Username: <input name="username" type="text" />
  Password: <input name="password" type="text" />
  <input value="Logon" type="submit" />
</form>

Next we’ll create login.jsp that will receive the values from this form

4. Right click over the project explorer and select new JSP page.
5. First we’ll check we’re receiving the param values correctly.
6. Add the following code within the body tags

<%
  String sServer = request.getParameter("CMS");
  String sUsername = request.getParameter("username");
  String sPassword = request.getParameter("password");
%>
<p>CMS: <%= sServer %></p>
<p>Username: <%= sUsername %></p>
<p>Password: <%= sPassword %></p>

7. To test that this is working, select loginForm.html and click the run icon.

The server should start if it is not already running and the login form should be displayed. Enter some values and click login. Your entered values should be displayed in the next screen.

Now we’ll update login JSP to use these values to login to BOE. First start your BOE server if it is not already running

8. Add the following import page directives right at the beginning of the JSP

<%@ page import="com.crystaldecisions.sdk.framework.*" %>
<%@ page import="com.businessobjects.foundation.exception.*" %>
<%@ page import="com.crystaldecisions.sdk.exception.*" %>

9. Now return to your code in the body tag and update it to look like the following,

<%
  String sServer = request.getParameter("CMS");
  String sUsername = request.getParameter("username");
  String sPassword = request.getParameter("password");
  String sSuccessFailMsg = "{empty}";

//login to BOE
  IEnterpriseSession eSession = null;  

try {
  final ISessionMgr sessionMgr = CrystalEnterprise.getSessionMgr();
  eSession = sessionMgr.logon(sUsername, sPassword, sServer, "secEnterprise");
  sSuccessFailMsg = "You have successfully logged on! BOE version: " +
      eSession.getEnterpriseVersion();
} catch (SDKException e) {
    sSuccessFailMsg = "Logon error: " + e.getMessage();
} catch (Exception e) {
    sSuccessFailMsg = "Logon error: " + e.getMessage();
}
%>  

<%= sSuccessFailMsg %>

10. Save this and test the code by executing the logon form. Note, when testing don’t use Administrator account in case you inadvertantly disable it, ideally create a test user account. A successful logon should display:

You have successfully logged on! BOE version: 1210

or an error if you have entered an incorrect username and password:

Logon error: Enterprise authentication could not log you on.
Please make sure your logon information is correct. (FWB 00008)

or if the server name is wrong or the BOE server is not running or not accessible a message,

Logon error: Server DEV_BOE not found or server may be down (FWM 01003)

To finish off we’ll update the application by adding a logout mechanism.

11. Return to login.jsp and add the following code highlghted in bold within the try statement

try {
  final ISessionMgr sessionMgr = CrystalEnterprise.getSessionMgr();
  eSession = sessionMgr.logon(sUsername, sPassword, sServer, "secEnterprise");
  sSuccessFailMsg = "You have successfully logged on! BOE version: " +
       eSession.getEnterpriseVersion();  

//Store BOE session object in web app session to retrieve later
  session.setAttribute("EnterpriseSession", eSession);
}

12. Also add the following which will display a logout button below the success message,

<form action="logout.jsp">
  <input value="Logout" type="submit" />
</form>

13. Now add a new JSP called logout.jsp – right click over Web Content in project folder and select New > JSP
14. Add the following page directive,

<%@ page import="com.crystaldecisions.sdk.framework.IEnterpriseSession" %>

15. And add the following code to the body,

<%
//Retrieve the BOE Session object
  IEnterpriseSession eSession =
    (IEnterpriseSession) session.getAttribute("EnterpriseSession");  

//close session
  session.removeAttribute("EnterpriseSession");  

if (eSession != null)  {
  eSession.logoff();
  eSession = null;
  session.invalidate();
}
%>  

<p%>You have now logged out.
Click <a href="http://www.gulland.com/wp/wp-admin/loginForm.html">here</a>
to login again.</p%>

16. Test the application in the same way and you should now be able to logout and login again.

Packaging Application in a WAR file

Once we’ve built our application we can package it in a WAR file to be deployed on another platform. This is exactly same as we did in part 1:

1. Right click on the project and select Export > WAR file
2. Update the name or keep default and enter a Destination for where the WAR file will be created
3. Click Finish and your WAR file is generated.

This WAR file contains all our code plus the BOE SDK JAR files we added to our project at the begining of the article. This means that we only need to deploye the WAR file on our target platform and don’t need to install any further BusinessObjects Enterprise software.

Integrating Java Doc for the BOE SDK

It is useful to have java doc integrated within Eclipse so that you can easily refer to the documentation while coding. First we need to download the doc from SAP BusinessObjects and then integrate into Eclipse.

To download the BOE SDK Documentaton,

1. Goto the SAP BOE Community website at http://www.sdn.sap.com/irj/boc
2. And from there select the link to SDK Library
3. Here we can see various packages, download the packages your require, for example, the XI 3.1 BOE Administration API can be dowloaded from http://help.sap.com/businessobject/product_guides/boexir31/en/boesdk_java_apiRef_12_en.zip
4. Save the ZIP to a suitable location and extract the contents

To integrate the documentation in Eclipse,

1. Return to Eclipse
2. Under your project expand Java Resources folder and then expand Libraries
3. For each of the BOE JAR files we added

biplugins.jar
cecore.jar
celib.jar
ceplugins_core.jar
cesdk.jar
logging.jar

4. Right click over the jar file and select properties in the left hand menu select JavaDoc location.
5. Click the Browse button and select the folder we contains the contents of the package we expanded above, should be the path ending in the folder “boesdk_java_apiRef_12_en”


Defining the Java Doc for the BOE SDK

6. Now when viewing code in a JSP or any other java class we can hover over a BOE class or object and help will pop-up display the text from the BOE SDK documentation.


Screenshot of Eclipse displaying javadoc for BOE SDK

That brings us to the end of this article and I hope you found it informative and that you have enjoyable and productive time coding BOE Web applications using Eclipse.