Provided in this kit are two versions of AgentRunner - a Java application program for debugging Notes/Domino agents in a Java IDE: AgentRunner.java for debugging agents that use the lotus.notes.noi (Notes/Domino Release 5) package classes and AgentRunner46.java for debugging agents that use the lotus.notes (Notes/Domino Release 4.6.x) package classes. Also included in this kit is a set of debug classes (in AgentRunner.jar) that access Notes context information while running in a Java IDE. You create your agent code to extend DebugAgentBase, then initially run the program as an agent inside Notes to generate an AgentContext document in AgentRunner.nsf. Subsequently you run the AgentRunner application which, in turn, runs your agent code outside Notes. The AgentRunner code accesses the AgentContext document to make the program behave as though it were running as an agent. This allows you to build and run without having to switch between the IDE and Notes, and to use IDE run-time tools such as the debugger.
Installing AgentRunner
For instructions on installing AgentRunner see readme.txt for the Domino Toolkit for Java.
Create a project for your agent
In Java IDE:
Copy (for example, for JDK or Cafe) to your project directory or Import (for example, for VisualAge) to your project, AgentRunner.java (or AgentRunner46.java) from the Tools\AgentRunner subdirectory. This file contains the main() entry point where execution will begin for agent debugging sessions.
Add the fully-qualified file specification for notes.jar and AgentRunner.jar (for example, for JDK or Cafe) to your Java IDE's CLASSPATH or Import (for example, for VisualAge) these files to your project.
Create an agent (see Java Programmer's Guide for instructions) that extends DebugAgentBase (instead of AgentBase).
Note: If you created agents with the 1.0 release of this toolkit, you should restructure your agent code to conform with this new format.
Build the project as an application.
Export (for example, for VisualAge) the .class files, if necessary.
Generate an AgentContext document
In Notes:
Create a Java agent in a Notes database and import the .class files from your project (it is not necessary to import AgentRunner.class). Ensure that the Base class is the class that extends DebugAgentBase.
Run the agent. This generates an AgentContext document in AgentRunner.nsf. Note that, when run in Notes, from an agent class that extends DebugAgentBase, a call to getSession() will, after generating an AgentContext document, return null. So any use of the returned session will result in a thrown exception. But, since the purpose of running the agent is only to generate the context document (and not to run any of the agent code), you can ignore the exception.
Open AgentRunner.nsf and examine the most recent AgentContext document. In particular, note the name of the server, the file path of the database, and the name of the agent. "Local" is the name of the server for a local database.
In edit mode, change the "Agent Runs On" and "Search Criteria" fields to generate the UnprocessedDocuments collection that you would like to use for debugging purposes. You must supply this information because it cannot be determined from running the agent (Note: the "Agent Runs On" and "Search Criteria" that you specified in the agent that you ran to generate this document will produce the "Selected" document list). Save and close the document.
You can generate another AgentContext document later if you want to change the run-time environment. You can edit fields other than "Agent Runs On" and "Search Criteria" to change the run-time environment, but this is not recommended.
Debug your agent
In Java IDE:
Specify <Agent> [<Database> [<Server>]] arguments (as displayed in the "AgentContexts" view of AgentRunner.nsf) to the AgentRunner program to select the AgentContext document that you want to use for debugging your agent code. If running from a command line, type:
java AgentRunner <Agent> [<Database> [<Server>]]
To run an agent that uses the lotus.notes package (from release 4.6.x) from a command line, type:
Set a breakpoint on the first executable line of code in the NotesMain() method of your agent.
Build the project.
Run or debug the project. If you are debugging and no breakpoints are set, you should step into NotesMain() to access your code.
Create the production agent
In Java IDE:
Change the Base class for your agent to extend AgentBase (instead of DebugAgentBase). This permits the agent to run normally rather than generate an AgentContext document.
Build the project.
Export (for example, for VisualAge) the .class files, if necessary.
In Notes:
Open the agent and reimport the .class files from the project.
Run the agent.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
$Info
$Body
PURSAFO
Edit Document
New AgentContext0
AgentContext
0S0E
Categori_zea
Send Docu_ment
_Forward
_Move To Folder...
_Remove From Folder4
Help
0S0E
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
;cQD=
$TITLE
$Index
$Formula
$FormulaClass
$ViewFormat
$Comment
$ACTIONS
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
_nmWd'[
c<-{(
$ACLDigest
CurrentDatabase_Server
CurrentDatabase_Server
Local
CurrentDatabase_Server
CurrentDatabase_FilePath"
3S4S8S9S10S11S13S15S17S18S19S20R
$16CurrentAgent$18$Conflict$REF$C1$
AgentContext
L1S-
$16CurrentAgent$18
MyHelloWorld
Local!!asdf
Local!!zxcv
zxcv
srv!!db
fromScratch
ServerAgent
AnotherServerAgent
AnotherHelloWorld
temp
MyAgent
Assign Hot Problems
Local!!c:\notes\data\INTRO.NSF
DbgAgent
tAgent$2$Conflict$REF$C1$
$16CurrentAgent$18$Conflict$REF
AgentContext
$17$16CurrentDatabase_Fi$Formula
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
$TITLE
$Index
$Formula
$FormulaClass
$ViewFormat
$Comment
Dre2R
Symbol
&Arial
About - AgentRunner
This tool provides Notes
agent context to a Java IDE. Once the context is set up, you can build, run, and debug without leaving the IDE. The code executes as it would in the Notes agent. This tool was developed and tested on Sun JDK, IBM VisualAge
, and Symantec Visual Cafe; it should work with other Java IDEs but was not tested in other environments. See the Using document
Java AgentRunner
for help.
Queries and comments should be directed to the "Developer Discussion Forum" at
http://www.lotus.com/developers
Copyright
Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the manner described in the software agreement.
Copyright 1998
Lotus Development Corporation
55 Cambridge Parkway
Cambridge, MA 02142
All rights reserved. Published in the United States.
Domino, InterNotes, Notes, and Lotus Domino Toolkit for Java are trademarks and Lotus, Lotus Notes, and SmartIcons are registered trademarks of Lotus Development Corporation. cc:Mail is a trademark of cc:Mail, a wholly-owned subsidiary of Lotus Development Corporation. IBM, OS/2, and VisualAge are registered trademarks of International Business Machines Corporation.
Other product and company names mentioned herein may be the trademarks or registered trademarks of their respective owners.
International Correctspell. English licensed from Houghton Mifflin Company. Copyright
1991 by Houghton Mifflin Company. All rights reserved. Reproduction or disassembly of embodied algorithms or database prohibited. Based upon The American Heritage Dictionary.
LOTUS DEVELOPMENT CORPORATION LICENSOR(S) MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE SOFTWARE. LOTUS DEVELOPMENT CORPORATION'S LICENSOR(S) DOES NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME JURISDICTIONS. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.
IN NO EVENT WILL LOTUS DEVELOPMENT CORPORATION'S LICENSOR(S), AND THEIR DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS (COLLECTIVELY LOTUS DEVELOPMENT CORPORATION'S LICENSOR(S)) BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE EVEN IF LOTUS DEVELOPMENT CORPORATION'S LICENSOR(S) HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
$Info
$Body
03/17/98 03:46:22 PM Robert Perron/CAM/Lotus deleted Richard Adams/CAM/Lotus
01/06/98 07:45:24 AM Richard Adams/CAM/Lotus added OtherDomainServers
01/06/98 07:45:24 AM Richard Adams/CAM/Lotus added LocalDomainServers
01/06/98 07:45:24 AM Richard Adams/CAM/Lotus updated Richard Adams/CAM/Lotus
01/06/98 07:45:24 AM Richard Adams/CAM/Lotus added Richard Adams/CAM/Lotus
-Default-
LocalDomainServers
OtherDomainServers
Local!!c:\lotus\notes\data\doc\javapg.nsf
g.nsf
Local!!c:\lotus\notes\data\doc\javapg.nsf
g.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
s\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
e%ras/CAM/No
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
e%ras/CAM/No
Local!!c:\lotus\notes\data\doc\javapg.nsf
g.nsf
Local!!c:\lotus\notes\data\doc\javapg.nsf
g.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
s\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
e%ras/CAM/No
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/
zathras/CAM/Notes!!api\api461.nsf
zathras/CAM/Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
e%ras/CAM/No
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\notes\data\problems.nsf
Local!!c:\lotus\notes\data\intro.nsf
Local!!c:\lotus\notes\data\intro.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c:\lotus\notes\data\javatest.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
zathras/CAM/No
Local!!c:\lotus\notes\data\javatest.nsf
zathras/CAM/No
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\notes\data\problems.nsf
\intro.nsf
ro.nsf
Local!!c:\lotus\notes\data\intro.nsf
ro.nsf
Local!!c:\lotus\notes\data\intro.nsf
ro.nsf
t.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
Local!!c:\lotus\notes\data\javatest.nsf
t.nsf
\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
Local!!c:\lotus\notes\data\javates
Local!!c:\lotus\notes\data\javatest.nsf
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
e%ras/CAM/No
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=
Local!!c
Local!!c:\lotus\notes\data\javatest.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/O=Notes!!api\api461.nsf
CN=zathras/OU=CAM/
CurrentAgent
(Debug AgentContext Data)"
4S6S8S9S
AgentContext'++LotusScript Development Environment:2:5:(Options):0:66
'++LotusScript Development Environment:2:5:(Forward):0:1
Declare Sub Exiting(Source As Field)
'++LotusScript Development Environment:2:5:(Declarations):0:2
'++LotusScript Development Environment:2:2:BindEvents:1:129
Private Sub BindEvents(Byval Objectname_ As String)
Static Source As FIELD
Set Source = Bind(Objectname_)
On Event Exiting From Source Call Exiting
End Sub
'++LotusScript Development Environment:2:2:Exiting:1:12
Sub Exiting(Source As Field)
End Sub
Java AgentRunner - AgentContext Data
Last Modified
Modified
Description
Description
Agent Runs On:
AgentRunsOnChange this to match generating agent
All documents in database | 0All new and modified documents since last run | 1All unread documents in view | 2All documents in view | 3Selected documents | 4Run once | 5
AgentRunsOn
AgentRunsOn
1S2S3S4R5S6S
AgentRunsOn
AgentRunsOn
AgentRunsOnView
You must supply a view name.{
4S5S6S7S8S9S11S12S13S14S16RS2E21RS2E
AgentRunsOnViewChange this to match generating agent
Search Criteria:
AgentSearchCriteriaChange this to match generating agent
Agent
CurrentAgent
CurrentAgent
You must enter a value for CurrentAgent
3S4S5S6S8S13SCurrentAgent
Database
CurrentDatabase
String
FilePath
CurrentDatabase_FilePath
You must enter a value for CurrentDatabase - FilePath
3S4S5S6S8S13SCurrentDatabase_FilePath
String
Server
CurrentDatabase_Server
CurrentDatabase_Server
3S4S9S11S15S
CurrentDatabase_Server
Document
DocumentContext
DocumentContext
DocumentContext
3S4S9S11SDocumentContext
String
EffectiveUserName
EffectiveUserName
EffectiveUserName
LastExitStatus
LastExitStatus
LastExitStatus
3S4S5S6S8S10SLastExitStatus
DateTime
LastRun
LastRun
Document
SavedData
SavedData
SavedData
3S4S9S11SSavedData
DocumentCollection
UnprocessedDocuments
AgentRunsOn
All documents in CurrentDatabase that meet Search Criteria
AgentRunsOn
All documents in CurrentDatabase minus "Processed" documents unmodified since "Processed On" that meet Search Criteria
AgentRunsOn
The intersection of all documents in View and "Selected" documents that meet Search Criteria
AgentRunsOn
All documents in View that meet Search Criteria
AgentRunsOn
All "Selected" documents that meet Search Criteria
(.txt)