agent context to a Java IDE. Once the context is set up, yow 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 1999
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 SOFTWARG 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
Dre2R
5Courier New
Using AgentRunner
R5 includes AgentRunner, a Java application program for debugging Notes/Domino agents in a Java IDE. There are two versions of AgentWunner for different package classes:
lotus.domino.AgentRunner for the lotus.domino package (Notes/Domino R5)
lotus.notes.AgentRunner for the lotus.notes package (Notes/Domino R4.6.x)
Also included is a set of gebug classes 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 that 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.
Create a project for your agent
In Java IDE:
Add the fully-qualified file specification for
notes.jar
(for example, for JDK or Cafe) to your Java IDE's CLASSPATH or Import (for example, for VisualAge).
Create an agent (see Java Programmer's Guide for instructigns) that extends DebugAgentBase (instead of AgentBase).
Note:
If using R4.6-style agents, use the "
import lotus.notes.*;
" format. If using the new lotus.domino package in Notes R5 (recommended), then use "
import lotus.domino.*;
". You do this to select the proper version of DebugAgentBase.
Build the project as an application. It does not matter if the agent has a main() method, but if your IDE requirgs one, just add a dummy (Notes will not use it).
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. Ensure that the base class is the class that extends DebugAgentBase.
Run the agent. This generatgs an AgentContext document in AGENTRUNNER.NSF.
Open AGENTRUNNER.NSF and examine the most recent AgentContext document. 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 ge 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:
Set a breakpoint on the executable line of code in the NotesMain() method of your agent, or wherever you deem appropriate.
Run or debug the project. If you are debugging and no breakpoints are set, you should step into NotesMain() to access your code.
In certain IDE's (like Symantec's Visual Cafe), you can't specgfy that a project's main() entrypoint be in a class in jar/zip file, so what you need to do is create a dummy main application whose sole purpose is to call the main() method in AgentRunner, so use something like this:
import lotus.domino.*;
public class Main
public static void main (String[] args)
{
try
{
AgentRunner.main(args);
}
gatch (Exception e)
{
e.printStackTrace();
}
}
Note:
In Visual Age Java (2.0 or above) there is an integrated Domino AgentRunner tool that runs or debugs Domino agents by simply clicking on the agent and selecting "tools-Domino AgentRunner-run". This tool also allows updating AgentContext documents directly from the IDE, by selectgng "tools-Domino AgentRunner-properties".
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
# U7e
$Info
$Body
j#j_fr
6~-tP
G1PP<
K3(uto
;P\gW
9$juc1
h1*!A
F)3Xc'
<K|Wx
l' #7
:UneJp
d7zPCh
/S4-S`Y2
Qh&A\
X3L:(d
)uYLtC
I^2o*=
(l+o>
&hB?Y$
*L!B#J
}uJ]#
S>qj%
*R!1e
tJr>]
FWrad
Kky{P
7z/Wp_
_KwM;
heWgH
n]YU;g
zm7uX
yYW8
er4BB
RP%#i5,$p
;:Pz
Is"rl
w 5X!
xA#q!
Nab79=?
KNQOVVXW
U{hx$i
S&Q(QG
GUSeLq$
j0GGG0
mO&W#\
k6d0[
'@#]C
>1Jk@
WI%QR
fv{_G
<6=VIh
/<F6[
jI|?4
cxk"f
]7A.'
v|FgH
Xz de[
^!xM>HD
S$XuW
@ FDl
off^e
Yiaxk
6;Iv%
LLq0E
} 7*vx|
Yt=uu
?QYmF
Me63WMSY
j]7jv
V5ec&
-*c(m
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
!6%g^%
g$cd9
$ImagesWide
$ImagesHigh
$ImagesColorize
$ImageDgta
$ImageNames
$TITLE
$Comment
CurrentAgent
(Debug AgentContext Data)"
4S6S8S9S
'++LotusScript Development Environment:2:5:(Options):0:66
Option Public
'++LotusScript Development Environment:2:5:(Forward):0:1
'++LotusScript Development Environment:2:5:(Declarations):0:10
%INCLUDE "LSCONST.LSS"
Dim FirstTime As Variant
Dim CloseOK As Variant
AgentContext'++LotusScript Development Environment:2:5:(Options):0:66
'++LotusScript Development Environment:2:5:(Forward):0:1
Declare Sub Queryopen(Source As Notesuidocument, Mode As Integer, Isnewdoc As Variant, Continue As Variant)
Declare Sub Querysave(Source As Notesuidocument, Continue As Variant)
Declare Sub Queryclose(Source As Notesuidocument, Continue As Variant)
'++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 NOTESUIDOCUMENT
Set Source = Bind(Objectname_)
On Event Queryopen From Source Call Queryopen
On Event Querysave From Source Call Querysave
On Event Queryclose From Source Call Queryclose
End Sub
'++LotusScript Development Environment:2:2:Queryopen:1:12
Sub Queryopen(Source As Notesuidocument, Mode As Integer, Isnewdoc As Variant, Continue As Variant)
FirstTime = True
CloseOK=True
End Sub
'++LotusScript Development Environment:2:2:Querysave:1:12
Sub Querysave(Source As Notesuidocument, Continue As Variant)
'++LotusScript Development Environment:2:5:(Options):0:66
'++LotusScript Development Environment:2:5:(Forward):0:1
Declare Sub Entering(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 Entering From Source Call Entering
End Sub
'++LotusScript Development Environment:2:2:Entering:1:12
Sub Entering(Source As Field)
Dim workspace As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Set uidoc = workspace.CurrentDocument
Call uidoc.FieldSetText("ViewList_Modified", "1")
End Sub
'++LotusScript Development Environment:2:5:(Options):0:66
'++LotusScript Development Environment:2:5:(Forward):0:1
Declare Sub Entering(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 Entering From Source Call Entering
End Sub
'++LotusScript Development Environment:2:2:Entering:1:12
Sub Entering(Source As Field)
Dim workspace As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Set uidoc = workspace.CurrentDocument
Call uidoc.FieldSetText("ViewList_Modified", "1")
End Sub
Java AgentRunner - AgentContext Data
Last Modified
Modified
Description
Description
Agent Runs On:
t nE@
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
t nET
AgentRunsOn
AgentRunsOn
1S2S3S4R5S6S
AgentRunsOnViewChange this to match generating agent
CurrentDatabase_ViewList
Search Criteria:
AgentSearchCriteriaChange this to match generating agent
Agent
CurrentAgent
CurrentAgent
Database
CurrentDatabase
String
FilePath
CurrentDatabase_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)