© 2006 Wellesley Information Services. All rights reserved.

Converting LotusScript Agents to Java Agents

Paul T. CalhounNetNotes Solutions Unlimited

2

What We’ll Cover …

• Comparing LotusScript Agents to Java Agents• Stepping through the process to convert LotusScript

Agents to Java Agents• Writing Code in Eclipse• Executing Java Agents

3

What We’ll Cover …

• Comparing LotusScript Agents to Java Agents• Stepping through the process to convert LotusScript

Agents to Java Agents• Writing Code in Eclipse• Executing Java Agents

4

LotusScript Agents vs. Java Agents

• Which one is faster?Both LotusScript and Java Agents call the same C++ code base

That means, all things being equal, Agents coded with Java will perform the same as Agents coded with LotusScript

5

Document Processing with LotusScript

• Standard LotusScript Agent that processes documents in a view

Sub InitializeDim s As NotesSessionDim db As NotesDatabaseDim vw As NotesViewDim doc As NotesDocumentDim names As String

Set s = New NotesSessionSet db = s.CurrentDatabaseSet vw = db.GetView(“ViewName")Set doc = vw.GetFirstDocument()

Do While Not (doc Is Nothing)names = names & doc.name(0) & Chr(13)Set doc = vw.GetNextDocument(doc)

LoopMsgbox names,0,"Motorcycle Names"

End Sub

6

Document Processing with Java

• EquivalentJava Agent

import lotus.domino.*;public class JavaAgent extends AgentBase {

public void NotesMain() {try {

Session session = getSession();AgentContext agentContext = session.getAgentContext();Database db = agentContext.getCurrentDatabase();View vw = db.getView(“ViewName");Document doc = vw.getFirstDocument();Document ndoc;

while (doc != null) {getAgentOutput().println(doc.getItemValueString("Name"));

doc.recycle();doc = ndoc; }

} catch(Exception e) {e.printStackTrace();}

}}

7

Document Processing with Java (cont.)

• Two primary differences in codeRetrieve data by data type

Java is a strongly “Typed” languageNo Variants (That’s a good thing. Really!)

Document recyclingOne of the biggest “Traps” that new Domino Java developers fall into

GOTCHA!

8

Comparisons

• Java AgentsStandardHost independent languageCode can be ported to other Java applicationsCan only access the back-end Domino objectsNo access to COM/OLE objectsJava is case sensitive

Yes it will ALWAYS be case sensitive

Java is strongly typedNo variants

• LotusScript AgentsProprietaryHost-based languageCode only executes on Domino servers/clientsFull access to back-end and front-end Domino objectsFull Access to COM/OLE objects on systemVariant data type available

Although no one uses them, right?

9

Why Code Java Instead of LotusScript?

• Use of Internet resourcesNative network I/O classes and methods for processing and accessing URLs for reading HTML or XMLBasis for consuming Web services (Web Service Clients)

• Communicate with resources using CORBA/IIOPAlternative to Java Remote Method Invocation (RMI) and Microsoft’s DCOM

10

Why Code Java Instead of LotusScript? (cont.)

• Performing complex tasks that Java does more efficiently

LotusScript is based upon the “basic” language that is not as powerful as a complete object-oriented language like Java

• You have the entire J2SE Java language at your disposal

• Using the Java language constructs for processing other than accessing the Domino back-end objects

Use existing Java Code or create your own classes

Building Block

11

Why Code Java Instead of LotusScript? (cont.)

• Taking advantage of Java’s multi-threading capabilitiesOn platforms with multi-processors

• Processing large document collections (especially from the Notes client)

Read thousands of documentsWrite many documents

12

Domino Back-End Class Names

• Only the back-end classes are exposed to JavaExposed via lotus.domino.*

• Wait a minute … YOU already know what 99%of the class names are

NotesSession SessionNotesDatabase DatabaseNotesView ViewNotesDocument Document

• Notice anything?Remove “Notes” from the front of all of the LotusScript class names and you have the equivalent Java class names

• Who knows those?That’s right, YOU DO!

Don't Forget

13

Domino Back-End Classes

• Classes that don’t exist in LotusScript:AgentBaseAppletBase and JAppletBaseNotesErrorNotesExceptionNotesFactoryNotesThread

14

LotusScript vs. Java In Action

Demo

Agents:Read Names JavaRead Names LotusScriptJava Network I/OHelpDocCount-LSHelpDocCount-JavaSlowHelpDocCount – Java

15

What We’ll Cover …

• Comparing LotusScript Agents to Java Agents• Stepping through the process to convert LotusScript

Agents to Java Agents• Writing Code in Eclipse• Executing Java Agents

16

Converting LotusScript Agents to Java Agents

• The Conversion ProcessThere are no automatic tools to convert LotusScript to Java Agents in Notes/Domino

YetSeveral Business Partners are working on this

Java Agents cannot access front-end objectsSo they are great for WebQuerySave and WebQueryOpen

LotusScript Agents that only do back-end processing are THE candidates for conversionCode the Java Agent to duplicate the functionality of the LotusScript Agent

Unless it was poorly written, then write it better!

17

Converting LotusScript Agents to Java Agents (cont.)

• Creating Java AgentsImported Java

To use Java classes written and compiled outside of the Domino Designer IDE

Only Option in Notes 4.xJava

Create an Agent from scratch in the Designer UIAvailable in R5, ND6, and ND7

18

Converting LotusScript Agents to Java Agents (cont.)

• To use imported Java programs, write class files in advance that meet these requirements:

For Domino/Notes 7.xUse Java SDK version 1.4.2

For Domino/Notes 6.xUse Java SDK version 1.3.1

For Domino/Notes 5.xUse Java SDK version 1.1.8

Extend the lotus.domino.AgentBase classBack-end classes are contained in the Notes.jar fileAgent code should start in NotesMain()

19

Converting LotusScript Agents to Java Agents (cont.)

• A New Java Agent automatically creates:A Java Source file

JavaAgent.javaBy default, Agents are not in packages

A compiled Class fileJavaAgent

This is the default Agent name, but it can be anythingA Starting Method

NotesMain();

20

Converting LotusScript Agents to Java Agents (cont.)

• Code base is automatically created with a try/catch block

• Remember, Java is CASE SENSITIVE

21

Converting LotusScript Agents to Java Agents (cont.)

• A Session and AgentContext object are created automatically

22

Converting LotusScript Agents to Java Agents (cont.)

• Place your code here!

23

Converting LotusScript Agents to Java Agents (cont.)

• Pre-compiled utilities and libraries as well as agent source code can be imported into any Agent

Click on the “Edit Project” buttonFind the resources on the file system and add them

24

Converting LotusScript Agents to Java Agents (cont.)

• External class references can also be added as a Notes.ini variable

Works in R5, ND6, and ND7Variable name

JavaUserClassesContent

Semi-Colon separated list

JavaUserClasses=(Path to class file in file system)

25

Converting LotusScript Agents to Java Agents (cont.)

• External class references can also be added to the ext folder in the jvm/lib Directory on the Notes Client and Domino Server

Works in ND6 and ND7

26

Converting LotusScript Agents to Java Agents (cont.)

• New Class buttonCreates a new Java Source file in your Agent

27

Converting LotusScript Agents to Java Agents (cont.)

• Export buttonExports the current Agent Source text out of Domino and into the file system using the name of the class file

JavaAgent.java

28

Converting LotusScript Agents to Java Agents (cont.)

• Compile buttonCompiles either the current Java class or the entire project

29

Converting LotusScript Agents to Java Agents (cont.)

• If there is an error in the code then it will appear in the “Errors” drop-down box

Successful message appears if there are no errors

30

Create New Agent In Domino Designer

Demo

31

What We’ll Cover …

• Comparing LotusScript Agents to Java Agents• Stepping through the process to convert LotusScript

Agents to Java Agents• Writing Code in Eclipse• Executing Java Agents

32

Writing Domino Code in the Eclipse Workbench

• Using the Eclipse Workbench, you can write: Java AgentsJava Script Libraries

Don’t confuse this with JavaScript LibrariesJava Servlets

• If you are going to be coding Servlets AND AgentsCreate a Dynamic Web Project

• If you are ONLY going to be coding AgentsCreate a Java ProjectNo need to download and install the J2EE code

Solution

33

Writing Domino Code in the Eclipse Workbench (cont.)

• Ensure you have installed and configured:Web Tools Plug-in (WTP)

Allows for the creation of Dynamic Web ProjectsPart of the Callistro ProjectJ2EE Runtime Test Server (If coding Servlet and JSPs)

JBossTomcatWebSphereWebLogic

34

Writing Domino Code in the Eclipse Workbench (cont.)

• In order for the Java Agents to compile you will need to include the following jar files in the Libraries Tab of the Projects Java Build Path property page (this is the classpath):

For Agents and Script LibrariesNotes.jar

Located in the Domino/Notes program directory(ND6)Located in the Domino/Notes jvm/lib/ext directory(ND7)

For ServletsNotes.jar for Local accessNCSO.jar for Remote(CORBA/DIIOP) access

Located in the Domino/Notes data/domino/java directory

35

Writing Domino Code in the Eclipse Workbench (cont.)

• Make sure you add the proper version of the .jar file for the target Notes/Domino environment

Warning

36

Coding a Java Agent

• Works in R5, ND6, and ND7• Create a new Java Agent in the Domino Designer client

Cut the Skeleton Code to the Clipboard

37

Coding a Java Agent (cont.)

• Create a new Java Class file in the Eclipse ProjectClass name should be indicative of agent functionalityRe-factor class name from “JavaAgent”Don’t worry about any of the other settings, the Agent code replaces themPaste the Java Agent code into the code editor window, replacing the existing generated codeCode completion and Pop-up help work just like coding LotusScript Agents in the Domino Designer client

38

Coding a Java Agent (cont.)

• Code completion and Pop-up help now work

39

Coding a Java Agent (cont.)

• Complete the code• Save the Source code in Eclipse• In the Domino Designer Client

Click on “Edit Project”Change the “Base Directory” to point to the Eclipse Projects “src” folderReplace the “JavaAgent” code with the source code created in EclipseChange the “Base Class” to reference the new class nameClick the “OK” button to import the source code into the agent designer and save it

40

Getting the Session and the Database

• Access the current database via agentContext or access a different database on this server via the session object

After this point, the code is SURPRISINGLY similar to LotusScript

Session session = getSession();

AgentContext agentContext = session.getAgentContext();

Database db = agentContext.getCurrentDatabase();

or

Database db=session.getDatabase("ServerName","DatabaseName");

41

Accessing the Data

• Access the documentsFrom a view

View vw = db.getView(“ViewName”);A document collection

DocumentCollection dc = db.getAllDocuments();Process the documents in a loop, accessing/updating values in each document

while (doc != null) {

System.out.println(doc.getItemValueString("FullName"));

ndoc = vw.getNextDocument(doc);

doc.recycle();

doc = ndoc;}

42

Writing Results

• Write status or results to appropriate outputSystem.out.println()getAgentOutput().println()

43

Two Methods for Producing Output

• Method 1: getAgentOutput() Implements a standard java.io.PrintWriter objectIf the Agent is executed from Domino/Notes, the output goes to the Java consoleIf the Agent is executed from a Web client, the output is written to the Web page

Basis for producing HTML/XML output to a Web browser

44

Two Methods for Producing Output (cont.)

• Method 2: System.out.println()If the Agent is executed in the background, output is written tothe Domino/Notes logIf the Agent is executed from the Notes/Designer client, output is written to the Java console

45

Recycling Memory

• When creating/reading many document objects, memory can become an issue

There is a recycle() method available to reclaim memory on instantiated objects in JavaCall the recycle() method as soon as the Agent is done with the documentUse the recycle() method to make objects available to the garbage collector

document.recycle();

46

import lotus.domino.*;public class JavaAgent extends AgentBase {public void NotesMain() {

try {Session session = getSession();Database db = session.getDatabase("", "Names.nsf");View vw = db.getView("($People)");Document doc,ndoc;doc = vw.getFirstDocument();while (doc != null) {System.out.println(doc.getItemValueString("FullName"));ndoc = vw.getNextDocument(doc);doc.recycle();doc = ndoc;

}

Agent Code for Looping – Part 1

47

} catch (Exception e) {e.printStackTrace();

}}

}

Agent Code for Looping – Part 2

48

Producing HTML Output

• The HTML rendering engine in Domino will try to process Agent output

Output from previous Agent when run in a Web client

49

Domino Attempts to Render HTML from the Agent

• The HTML rendering engine in Domino will try to process Agent output (cont.)

The source view from the Web client

50

Overriding the Domino Default

• By setting the MIME type of the output, you can override the default rendering

To produce HTML outputContent-type:text/html

• This will require you to produce ALL of the HTML in your Agent output

51

import java.io.PrintWriter;//Create a Java PrintWriter object variable to save coding time and sizePrintWriter webout = getAgentOutput();//Set the content typewebout.println("Content-type:text/html");webout.println("");

Coding for Output

• Shorten the code by creating a Java PrintWriter instead of using the getAgentOutput().println() method in every line of code

PrintWriter is a class in the java.io package

52

import lotus.domino.*;import java.io.*;public class JavaAgent extends AgentBase {

public void NotesMain() {try {

Session session = getSession();// AgentContext agentContext = session.getAgentContext();// (Your code goes here)Database db = session.getDatabase("", "Names.nsf");View vw = db.getView("($People)");Document doc;Document ndoc;doc = vw.getFirstDocument();PrintWriter webout = getAgentOutput();webout.println("Content-type:text/html");

Agent to Produce HTML Output – Part 1

53

webout.println("");webout.print("<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>");webout.print("<html><head><meta http-equiv='Content-Type' content='text/html; charset=ISO-8859-1'>");webout.print("<title>My First HTML Page</title></head><body>");webout.print("<h1>Names From Name and Address Book</h1>");webout.print("<br /><br />");while (doc != null) {

webout.print(doc.getItemValueString("FullName"));webout.print("<br />");ndoc = vw.getNextDocument(doc);doc.recycle();doc = ndoc;

}webout.print("</body></html>");} catch (Exception e) {

e.printStackTrace();}

}}

Agent to Produce HTML Output – Part 2

54

Producing HTML Output with a Java Agent

• HTML output from the Agent

55

import lotus.domino.*;import java.io.PrintWriter;public class JavaAgent extends AgentBase {

public void NotesMain() {try {

Session session = getSession();AgentContext agentContext = session.getAgentContext();//get the server name from the current databaseDatabase cdb = agentContext.getCurrentDatabase();String ServerName = cdb.getServer();//Access the Database this agent is running inDatabase db = session.getDatabase(ServerName,"names.nsf");//Access the People ViewView pview = db.getView("($People)");

Agent to Produce XML Output – Part 1

56

//Create Variables to hold the Documents and get the first documentDocument doc;Document ndoc;doc = pview.getFirstDocument();

//Create a Java PrintWriter object variable to save coding time and sizePrintWriter pw = getAgentOutput();

//Set the content typepw.println("Content-type:text/xml");pw.println("");

//Write out the XML Opening Tagspw.println("<?xml version='1.0' ?>");pw.println("<PeopleList>");

Agent to Produce XML Output – Part 2

57

Agent to Produce XML Output – Part 3

//Create a while loop to process the document in the Viewwhile (doc != null) {//Write the value in the FullName field to the output streampw.println("<Person>");pw.println(doc.getItemValueString("FullName"));pw.println("</Person>");//Get the next document in the view and store to the placeholderndoc = pview.getNextDocument(doc);//recycle the doc object to preserve memorydoc.recycle();//set the doc object equal to the placeholderdoc = ndoc;}

58

}//close the root tag

pw.println("</PeopleList>");

} catch(Exception e) {

e.printStackTrace();}

}}

Agent to Produce XML Output – Part 4

59

XML Output from the Agent

60

Outputs in HTML and XML

Demo

Agents:HelloWorld.javaOutputNamesToHTMLOuputNamesToXML

61

What We’ll Cover …

• Comparing LotusScript Agents to Java Agents• Stepping through the process to convert LotusScript

Agents to Java Agents• Writing Code in Eclipse• Executing Java Agents

62

Executing Java Agents

• Java Agents can be executed all of the same ways as a LotusScript Agents

• Remember that there is no interaction with the Notes UI• Write agent status to

Notes LogAgent LogDocument in a Database

63

Executing Java Agents

• Java Agent security functions the exact same way LotusScript security does

• Many Java Agent Access Network (File and URL) resources

• Set runtime security to2. Allow restricted operations

GOTCHA!

64

Executing Java Agents

• The best candidates for Java Agents areForm Events (These are easily transitioned to servlet processing)

WebQueryOpenWebQuerySave

AgentsScheduled Agents

65

Java Agents for WebQuerySave

Demo

Forms:WebQuerySaveExampleAgents:

WebQuerySave

66

Resources

• TLCChttp://www.tlcc.com

• Head First Java SeriesHead First Java Head First Servlets and JSPs

• IBM Redbookshttp://www.redbooks.ibm.com/

Connecting Domino to the Enterprise Using JavaR5 Best Practice GuideLotus Domino R5.0: A Developer's HandbookDomino and WebSphere TogetherXML Powered by Domino

67

Resources (cont.)

• THE VIEWMany Java articles, here are a couple …

“Multi-threaded Java/CORBA Agents for Remote Server Access,” July/August 2000“Programming for Performance with LotusScript and Java,” November/December 1998

• IBM Alphaworks and Developerworkshttp://www.alphaworks.ibm.com/http://www.ibm.com/developerworks/java

68

7 Key Points to Take Home

• Java Agents can be used in place of LotusScript Agents for back-end processing

QuerySave / QueryOpenWebQuerySave / WebQueryOpen

• Java performs equivalent to LotusScript because both call the same C++ code base

• Java Agents can produce HTML output• Java is CASE SENSITIVE!

69

7 Key Points to Take Home

• Java Agents can produce XML output• Java is better at working with network

resources than LotusScript• Java is the programming language of choice for coding

Web solutions outside of Domino (servlets, JSPs)

70

Your Turn!

Questions?

How to Contact Me:Paul T. Calhoun

pcalhoun@nnsu.com

Add “view” to emailSubject line