JDEUser’s Guide

Paul Kinnucan

March7, 2001

Contents

0.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

0.1.1 About theJDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

0.1.2 JDERequirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

0.1.3 JDEComponents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

0.1.4 LatestVersion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

0.1.5 ContactingtheAuthor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

0.2 EditingJavaSourceFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

0.3 DocumentingCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

0.3.1 InsertingJavadocComments. . . . . . . . . . . . . . . . . . . . . . . . . 5

0.3.2 GeneratingtheDocumentation. . . . . . . . . . . . . . . . . . . . . . . . 5

0.4 CodeCompletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

0.4.1 JavaKeywordCompletion . . . . . . . . . . . . . . . . . . . . . . . . . . 5

0.4.2 ControlStructureCompletion . . . . . . . . . . . . . . . . . . . . . . . . 6

0.4.3 DynamicKeywordCompletion . . . . . . . . . . . . . . . . . . . . . . . 6

0.4.4 Field andMethodCompletion . . . . . . . . . . . . . . . . . . . . . . . . 7

0.5 GeneratingCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

0.5.1 CodeWizards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

0.5.2 CodeTemplates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

0.5.3 PointTemplates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

0.5.4 CustomizingTemplates. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

0.5.5 CreatingTemplates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

0.6 CompilingJavaPrograms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1

0.6.1 CompilationOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

0.7 Building JavaApplications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

0.7.1 Build Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

0.7.2 SampleMakefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

0.8 RunningJavaApplications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

0.8.1 SettingVM Command-LineArguments. . . . . . . . . . . . . . . . . . . 23

0.8.2 SettingCommand-LineApplicationArguments. . . . . . . . . . . . . . . 23

0.8.3 RunCustomizationVariables. . . . . . . . . . . . . . . . . . . . . . . . . 23

0.9 Workingwith Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

0.9.1 RunningApplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

0.9.2 DebuggingApplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

0.9.3 AppletCustomizationVariables . . . . . . . . . . . . . . . . . . . . . . . 25

0.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

0.11 SettingaGlobalClasspath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

0.12 UsingProjectFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

0.12.1 How theJDEFindsProjectFiles . . . . . . . . . . . . . . . . . . . . . . . 27

0.12.2 ProjectFile Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

0.12.3 Creatinga ProjectFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

0.13 DisplayingJavaDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

0.13.1 BrowsingJDK Documentation. . . . . . . . . . . . . . . . . . . . . . . . 28

0.13.2 Context-SensitiveClassHelp . . . . . . . . . . . . . . . . . . . . . . . . . 28

0.14 BrowsingSourceCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

0.14.1 jde-show-class-sourceCommand . . . . . . . . . . . . . . . . . . . . . . 29

0.14.2 ClassesIndex Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

0.14.3 UsingtheSpeedbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

0.14.4 Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

0.15 CustomizingtheJDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

0.15.1 CustomizationVariables . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

0.15.2 SettingaVariable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

0.15.3 JDECustomizationGroups . . . . . . . . . . . . . . . . . . . . . . . . . 34

0.16 Customizingjde-mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

0.16.1 CustomizingKey Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2

1 JDE User’sGuide

1.1 Intr oduction

Welcometo the JDE User’s Guide . This guide explains how to usethe JDE to develop Javaapplicationsandapplets.Theguideassumesthatyouarefamiliar with EmacsandJavaSoft’sJavadevelopmenttools.

1.1.1 About the JDE

The Java DevelopmentEnvironment(JDE) is an EmacsLisp packagethat interfacesEmacstothird-party Java applicationdevelopmenttools, suchas thoseprovided by JavaSoft’s Java De-velopmentKit (JDK). The resultis an integrateddevelopmentenvironment(IDE) comparableinpower to many commercialJava IDEs. Featuresinclude:

� sourcecodeeditingwith syntaxhighlightingandautoindendation

� automaticcompletionof classfieldsandmethods

� compilationwith automaticjumpfrom errormessagesto responsibleline in thesourcecode.

� generatesclassandmethodskeletonsautomatically

� run Javaapplicationin aninteractive(comint)Emacsbuffer

� integrateddebuggingwith interactive debug commandbuffer andautomaticdisplayof cur-rentsourcefile/line whensteppingthroughcode

� browseJDK doc,usingthebrowserof yourchoice

� browseyour sourcecode,usingtheEmacsetagsfacility or a tree-structuredspeedbar.

� supportslatestversionof JavaSoft’sJavaDevelopmentKit

� runsonany platformsupportedby EmacsandSun’sJavaSDK (e.g.,Win95/NTandSolaris)

� easilyandinfinitely customizable

� workswith FSFEmacsandXEmacs

1.1.2 JDE Requirements

TheJDErequiresthefollowing software:

� FSFEmacsor XEmacson Unix platforms; the 20.6.1versionof NT/Emacson Windowsplatforms,for generalsourcefile editingandtool integrationfunctions.

3

� JavaDevelopmentKit (JDK) or compatiblesetof Java developmenttools(compiler, virtualmachine,debugger, classlibraries,etc.)

� Webbrowser(e.g.,Netscapeor InternetExplorer)for viewing documentation.

� latestversionsof Eric Ludlam’s speedbarand semanticbovinator packagesavailable fordownloadfrom Eric’shomepage

� bashor otherUnix-styleshellhighly recommendedfor Windows95/NTenvironments.

1.1.3 JDE Components

TheJDEdistribution includesthefollowing files:

� jde.el.Definesjde-mode,amajorEmacsmodefor developingJavacode.

� jde-run.el.RunsJavaapplicationsandapplets

� jde-db.el. InterfacesEmacsto jdb, thecommand-linedebuggerthatcomeswith theJDK.

� jde-gen.el.Containscodegenerationtemplates.

� bsh.jar. Compiledfiles for the BeanShell,a Java sourcecodeinterpreterdevelopedby PatNeimeyer.

� beanshell.el.ProvidesanEmacsinterfaceto theBeanShellinterpreter.

� jde-wiz.el. Provides “wizards” that generateskeleton implementationsof interfacesandskeletonoverridesof methodsdeclaredby superclasses.

� jde-complete.el.Automaticfield andmethodcompletionpackage.

� jde-parse.el.Javaparserpackage.

� java.bnf.Javagrammarusedto generatetheJDE’s lisp-basedJavaparser.

� jde-bug.el.JDEbuguserinterfacepackage.

� jde-dbs.el.JDEbug low-level commandinterfacepackage.

� jde-dbo.el.JDEbugoutputprocessingfunctions.

� sourcecode,jar files,anddocumentationfor theJavacomponentsof theJDE.

� jtagsis abashshellscriptthattagsJavasourcehierarchies.

� jtags.cshis ac shellscriptthattagsJavasourceheierarchies.

4

1.1.4 Latest Version

Seethe EmacsJDE HomePagefor instructionson downloadingand installing the most recentversionof theJDE.

1.1.5 Contacting the Author

Pleasesendbugreportsandenhancementsuggestionsto Paul Kinnucan.

1.2 Editing Java SourceFiles

To edit an existing Java sourcefile, load it into an Emacsbuffer by executingC-x C-f. Loadinga Java sourcefile into a buffer causesthe buffer to enterinto jde-mode,a variantof java-mode,which is in turn a variantof the standardEmacscc-modefor editing sourcefiles written in Candrelatedlanguages.Jdemodeoffers all the specializedsourcefile editing commandsof cc-modeplusfunctionsfor compiling,running,anddebuggingJava sourcefiles. You caninvoke thecommandsby selectingthemfrom theJDE menuthat jde-modedisplayson theEmacsmenubaror by typing thecommandsin theEmacsminibuffer (seethefigurebelow).

1.3 DocumentingCode

The JDE providescompletesupportfor generatingHTML documentationfor Java classesfromcommentsinsertedinto thesourcecodefor thoseclasses.

SeeAlsoDisplayingJavaDocumentation

5

1.3.1 Inserting JavadocComments

To inserta skeletonjavadoccommentfor a classor method,positionpoint in thefirst line of themethodor classandselectJDE- � Documentfrom theEmacsmenubaror typeC-cC-v j.

To customizethe javadocskeletons,selectJDE- � Options- � Project- � Javadoc from theEmacsmenubar.

NoteThanksto David Poncefor developingtheJDE’s javadoccommentgenerationfacility.

1.3.2 Generating the Documentation

To generatedocumentationfor the currentproject,openany sourcefile in the projectandselectMakeDoc from theJDE menuor enterM-x jde-javadoc-make.

Thejde-javadoc-makerunstheJDK’sjavadocprogramto generatethedocumentation.Thejavadoccommandmustbeon your system’scommandpath.

The jde-javadoc-make commandusesjde-global-classpathas the -classpathand jde-db-source-directoriesasthe-sourcepathoptionfor generatingthedoc. You canspecifyall otherjavadocop-tionsvia JDEcustomizationvariables.Tospecifytheoptions,selectProject- � Options- � Javadocfrom the JDE menu. Use jde-javadoc-gen-packagesto specify the packages,classes,or sourcefiles for whichyouwantto generatejavadoc.If thisvariableis nil, thejde-javadoc-makegeneratesjavadocfor theJavasourcefile in thecurrentbuffer.

NoteThanksto Sergey A Klibanov for developingtheJDE’s javadocgenerationfacility.

1.4 CodeCompletion

With the JDE, you canenterthe first few lettersof a Java keyword, field, or methodnameandthenhave theJDEentertheremainingcharacters.Whencompletingmethods,theJDEentersthemethodargumentsaswell. Thefollowing sectionsdescribesthecompletionoptionsthat theJDEoffers.

1.4.1 Java Keyword Completion

TheJDEdefinesa setof abbreviationsfor Java keywords. Whenyou typeoneof theseabbrevi-ationsfollowed by a spacein a Java sourcebuffer, the JDE optionally expandsthe abbreviationinto the keyword. For example,whenthe abbreviation modeis enabled,you needonly type fafollowed by a spaceto enterthe Java keyword false. To enableor disableabbreviation mode,selectJDE- � Project- � Options- � General and toggle the booleanvariablejde-enable-abbrev-mode.To change,remove,or addanabbreviation,edit thevariablejde-mode-abbreviationsin theprojectcustomizationbuffer.

Note TheJDE’s Javakeyword expansionfacility is basedon theEmacsabbrev-modefacility. Formoreinformation,seetheEmacsusermanual.

6

1.4.2 Control Structure Completion

TheJDEdefinesabbreviationsfor Javacontrolstructures,suchasif-then-else.Whenyouentertheabbreviation followedby a space,theJDEexpandstheabbreviation into a correspondingcontrolstructuretemplate.For example,

ife

expandsto thecontrolstructuretemplate

if ( )�

�// endof if ()

else�

�// endof if ()elseControl Flow Abbreviations

TheJDEdefinesthefollowing abbreviationsfor controlstructures.

StatementAbbreviationif-thenif elseelse if-then-elseife whilewhile forfor for (int I=0;I � UL;I++)for mainmethodmain switchswitch casecase

NoteYou mustenabletheJDE’sJavakeywordabbreviation modeto usethecontrolflow abbrevi-ations.SeeJavaKeywordCompletionfor moreinformation.Left BracePlacement

The JDE’s Java control flow templatessupporttwo optionsfor openingbraceplacement:place-menton thefirst line of thetemplate(Kerningham& RitchieStyle,thedefault) andplacementona separateline. Type M-x customize-variablejde-gen-k&rto specifythe style you prefer. Cus-tomizing the Control Flow Templates

You cancustomizethetemplatesto suit any indentationstyle. To customizethetemplates,selectProject- � Options- � Autocodefrom theJDEmenu.Enabling Variable Content

Sometemplatesoptionallypromptyou for itemsto insertinto thetemplate.To enableprompting,set the variabletempo-interactive to a non-nil valuein your .emacsfile. Disabling the ControlFlow Abbreviations

To disablethecontrolflow abbreviations,setthevariablejde-gen-cflow-enableoff. Acknowledge-ments

Thanksto Eric D. Friedmanfor contributing thecontrolflow templates.

1.4.3 Dynamic Keyword Completion

Emacsprovidesdynamiccompletioncommandsattemptto find completionsfor theword at pointin thecurrentbuffer or otherbuffers.For example,supposethatthecurrentsourcebuffer containstheclassnamesComponentandContainer. Now supposeyou enterCo somewherein thebufferand type M-/. EmacscompletesCo to Component.Typing M=/ againchangesComponenttoContainer. In this way, you cancycle throughall the possiblecompletionsfor Co in the currentbuffer.

7

Emacsprovidestwo dynamiccompletioncommands:dabbrev-expand,which is boundto thekeysequenceM-/ by default, andhippie-expand.Thedabbrev-expandcommandsearchesthecurrentbuffer for completionsof theword at point and,if nonearefound,otherbuffersof thesametype.For example,if thecurrentbuffer is a Java sourcebuffer, it searchesotherJava sourcebuffersforcompletionsif noneare found in the active buffer. The hippie-expandprovidesmoreextensivesearchcapabilities.Seethedocstringsfor thesefunctionsfor moreinformation.

1.4.4 Field and Method Completion

The JDE provides two commandsfor completinga Java field or methodnameat point in thecurrentbuffer: jde-complete-at-point(C-c C-v .) andjde-complete-at-point-menu(C-c C-v C-.).jde-complete-at-point

This commandfindsall thefieldsandmethodsthatcompletethenameat point. It theninsertsthefirst potentialcompletionin the buffer at point. Repeatedlytyping C-c C-v . causesthe JDE tocycle throughtheotherpotentialcompletions.If thecompletionis a methodname,thecommandcompletesthe methodnameanddisplaysthe methodsignaturein the minibuffer. For example,typing C-cC-v .

String s;s.get

ˆ

completesthemethodnameat point asfollows

String s;s.getClass(

ˆ

anddisplays

java.lang.ClassgetClass()

in the minibuffer. Repeatedlytyping C-c C-v . cyclesthroughall the otherget methodsfor theJavaStringclass.

Thiscommandworksfor all of thefollowing cases.

� objectsreferencedby variablesdeclaredin thecurrentbuffer

� staticfieldsandmethods

8

� fieldsandmethodsof objectsdefineby thecurrentclassandits parent

Namesof fieldsandmethodsof thecurrentclassmuststartwith thisor . (period).Namesoffieldsandmethodsdeclaredby theparentof thecurrentclassmuststartwith super.

For example,thiscommandcompletes

.ˆ

this.ˆ

super.ˆ

� objectsreferencedby the fields of objectsreferencedby variablesdeclaredin the currentclassor its parentor by staticfields.

For example,thiscommandcompletes

System.out.prinˆ

� objectsreturnedby methodsof objectsreferencedby variablesdefinedin thecurrent

For example,thiscommandcompletes

Toolkit.getDefaultToolkit().getˆ

� objectsreferencedby methodparameters

For example,thiscommandcompletes

void setColor(String color) {color.get

ˆ}

9

The jde-complete-at-pointcommandusestheBeanshellto run Java codethat in turn usesJava’sreflection(classintrospection)capabilityto determinethefieldsandmethodsdefinedfor theclassof objectatpoint. ThecommandstartstheBeanshellif it is notrunning.Thiscancauseanoticeabledelayin theexecutionof thecommandthefirst time it is usedin a session.Theresponsecanalsobeslow for classescontainingmany methodsandfields.

The completioncommandworks only for compiledclassesthat residein the classpathdefinedby jde-global-classpathwhentheBeanshellstarts.Thus,if thecommandis unableto completeamethodor field, makesurethattheclassthatdefinesthefield or methodis compiledandexistsonjde-global-classpath.jde-complete-at-point-menu

This commandworksexactly like jde-complete-at-pointexceptthat it displaysthepotentialcom-pletionsfor a field or methodin a popupmenu.Selectinga completionfrom themenucausesthecommandto useit to completethemethodor field at point.

1.5 GeneratingCode

TheJDEprovidesthefollowing codegenerationcapabilities.

� Codewizards

� Codetemplates

1.5.1 CodeWizards

TheJDEprovidescodegenerationwizardsthatgenerateclass-dependentcodewithout requiringyou to supplyany otherinformationthantheunqualifiednameof theclass.

The wizardsusethe BeanShellto run a Java utility that searchesthe classpathspecifiedby jde-global-classpathfor classesthatmatchtheunqualifiedname.If awizardfindsmorethanoneclassof thesameunqualifiednameon theclasspath,i.e.,a classthatexistsin morethanonepackage,itpromptsyou to selectoneof theclasses.

Note A wizardstartstheBeanshellinterpreterif it is not alreadyrunning. Thus,you mayexperi-encea slightdelaywheninvokingawizardfor thefirst time in asession.Import Wizard

Theimportwizardgeneratesanimportstatementfor theclassnameatpoint if animportstatementdoesnot alreadyexist for thatclass.Thewizardgeneratestheimport statementat theheadof thesourcebuffer.

To import theclassat point, selectJDE- � Wizards- � Import Classfrom theEmacsmenubarortypeC-c C-v C-z.

The import wizard searchesthe currentclasspathfor classesthat matchthe classnameat point,which maybeunqualified.If theimport wizardfindsmorethanoneclassof thesameunqualifiednameon thecurrentclasspath,it promptsyou to selectoneof theclassesto import.

NoteTheclasspaththattheimportwizardsearchesfor importcandidatesis theclasspathspecifiedby jde-global-classpathwhentheBeanShellwaslaststarted.

10

Thecustomizationvariablejde-wiz-import-excluded-packagesallowsyouto specifya list of pack-agesto excludefrom considerationfor import into thecurrentsourcefile. If theimportwizardfindsany classeson theclasspaththatbelongto the list of prohibitedpackages,it removesthemfromthelist of classesconsideredfor import. Method Override Wizard

Themethodoverridewizardgeneratesaskeletonmethodthatoverridesasimilarly namedmethoddefinedby asuperclass.

To overridea methodof asuperclass:

1. PositiontheEmacspoint at thelocationin thebuffer whereyou wantthegeneratedmethodto appear.

Thepointmustbewithin theclassthatis overridingthemethod.

2. SelectWizards- � Override Method from the JDE menuor enterM-x jde-wiz-overrided-method.

TheJDEpromptsyou to enterthenameof themethodto beoverriddenin theminibuffer.

11

The namemustbe the nameof a methoddefinedby an ancestorof the classin which theEmacspoint is located.Thecompiledclassof theancestormustbeontheclasspathspecifiedby jde-global-classpath.

3. Enterthenameof themethodto beoverridden.

If the ancestorsof the classin which you areoverriding the methoddefinemorethanonemethodof the samename,the wizard displaysa dialog buffer that lists the methods.Forexample,Java’s awt classhierarchydefinesseveral variantsof the methodrepaint. If youspecifyrepaintasthemethodto override,theJDEdisplaysthefollowing dialogbuffer:

The dialog buffer lists the signatureof eachvariantof the methodyou specified. Next toeachsignatureis aradiobutton.Theradiobuttonof thecurrentlyselectedsignaturecontainsanasterisk.To selectanothersignature,right-click theradiobuttonnext to thevariant. Toconfirmyourselectionanddismissthedialog,right-click the[Ok] button.

4. Selectthemethodvariantyouwantto overrideandclick the [Ok] button.

12

Thewizard insertsa skeletonimplementationof theselectedmethodat thecurrentpoint intheJavasourcebuffer.

Thewizardalsoinsertsimport statementsfor any classesreferencedby themethodthatarenotalreadyimportedby thecontainingclasseitherexplicitly or implicitly. Thewizardinsertsthe import statementsat theheadof thesourcebuffer afterany existing import statements,or any packagestatement,or thefirst blankline in thebuffer.

Note: The methodoverridewizard usestheBeanShellto createthe interfaceimplementa-tion. If the BeanShellis not currently running, the wizard startsthe BeanShell. Thus, ifthe BeanShellis not alreadyrunning,you may experiencea shortpausethe first time youoverrideamethod.

Interface Wizard

This wizardcreatesa skeletonimplementationof any interfacedefinedon theclasspathspecifiedby jde-global-classpath.

To createanimplementationof aninterface:

1. If theinterfaceis to beimplementedby anew class,createtheclassin abuffer.

2. PositiontheEmacspoint at thepoint in theclasswhereyou wanttheimplementationof theinterface’s methodsto appear.

3. SelectWizards- � Implement Interface from theJDE menuorenterM-x jde-wiz-implement-interface.

TheJDEpromptsyou to enterthenameof theinterfaceto beimplemented.

4. Enterthefully qualifiednameof theinterface.For example,java.awt.Event.MouseListener.

Thewizardinsertsskeletonimplementationsof themethodsdeclaredby theinterfaceat thecurrentpoint in the currentbuffer. It insertsimport statementsfor any classesrequiredbytheinterfaceat theheadof thecurrentbuffer (only if import statementsdo not alreadyexistfor therequiredclasses).It alsoupdatesor createsanimplementsclausefor theclass.

13

Note: The interfacewizard usesthe BeanShellto createthe interface implementation. If theBeanShellis not currentlyrunning,it startstheBeanShell.Thus,if theBeanShellis not alreadyrunning,youmayexperiencea shortpausethefirst timeyouusethewizard.DelegateWizard

This wizardgeneratesmethodsthatdelegatecalls to a classin thecurrentbuffer to anattributeofthe class,i.e., to an object that is a field of the currentclass. For example,if the currentbuffercontainsclassA andA hasanattribute,A.b, thatis aninstanceof classB, thiswizardgeneratesallthepublicmethodsof classB in A anddelegatehandlingof thosemethodsto b.

AcknowledgementThanksto CharlesHart for contributing this wizard.

1.5.2 CodeTemplates

Buffer Templates

Thesecommandscreatebufferscontaininga skeletonJava class.Eachcommandpromptsyou toenterthe pathto a new Java sourcefile. They thencreatea buffer for the new file andinsertatemplatefor aclassof thesamenameasthenewly createdfile. In particular, thecommand

� Files-� JDE New-� Classcreatesabuffer containingagenericJavapublic class.

� Files-� JDE New-� Consolecreatesa buffer containingthe main classof a Java consoleapplication.

� Files-� JDE New-� Other promptsyouto createany of theabovebuffersor acustom(user-defined)buffer.

You cancreatean emptyJava classbuffer by selectingFiles-� Open (C-x C-f) andenteringthepathfor anew file whoserootnameis thesameastheclassyouwantto createandwhoseextensionis .java. SpecifyingBoilerplate Text

You canspecify boilerplatetext (for example,a copyright notice) to be insertedat the headofclasssourcefiles createdby theJDE.TheJDEprovidestwo waysto specifytheboilerplatetext.Thesimplestway is to enterthelinesof boilerplatetext asthevalueof thecustomizationvariablejde-gen-buffer-boilerplate.Anotherway to specifythetext is to setthevalueof thecustomizationvariablejde-gen-boilerplate-functionto a functionthatgeneratestheboilerplatetext. (Thedefaultvalueof thisvariableis jde-gen-create-buffer-boilerplate,whichreturnsthevalueof theboilerplatevariable,jde-gen-buffer-boilerplate).The functionalapproachallows you to generateboilerplatetext dynamicallyby evaluatingthe appropriateLisp code. By saving the valuesof boilerplatevariablesin projectfiles,youcanspecifydifferentboilerplatetext for eachproject.CustomizationVariables

Thefollowing JDEcustomizationvariablescontrolcreationof autocodedJavasourcebuffers:

14

Variable Group Usagejde-gen-class-buffer-template Autocode Templatefor agenericpublic classbuffer.

jde-gen-console-buffer-template Autocode Templatefor aconsoleapplicationbuffer.jde-gen-jfc-app-buffer-template Autocode Templatefor aJFC(Swing)application.

jde-gen-buffer-templates Autocode Specifiestemplatesavailableto createJavabuffers.jde-gen-buffer-boilerplate Autocode Specifieslinesof text to beinsertedat theheadof classfiles.

jde-gen-boilerplate-function Autocode Specifiesa functionthatreturnsastringof boilerplatetext. Thedefault valueis jde-gen-create-buffer-boilerplate,which returnsthevalueof jde-gen-buffer-boilerplate.

SeeCustomizingAutocodeTemplatesfor information on how to customizethe classautocodetemplates.

1.5.3 Point Templates

Thefollowing commandsinserttemplatesat thecurrentpoint in thebuffer:

� JDE- � Generate-� Get/SetPair generatesaninstancevariableandagetandsetmethodforthatvariable

� JDE- � Generate-� Println generatesa System.out.println(...);statement.

� JDE- � Generate-� Listener- � Action generatesandregistersanactionlistenerfor a speci-fiedcomponent.

� JDE- � Generate-� Listener- � Window generatesandregistersawindow listenerfor aspec-ified window.

� JDE- � Generate-� Listener- � Mouse generatesandregistersa mouselistenerfor a speci-fiedcomponent.

� JDE- � Generate-� Other allowsyouto selectany of theabovetemplatesor acustom(user-defined)template.

Thefollowing variablescontrolgenerationof codeat point:

Variable Group Usagejde-gen-get-set-var-template Autocode Definesa get/setmethodpair template.

jde-gen-listener-action-template Autocode Definesanactionlistenertemplate.jde-gen-listener-window-template Autocode Definesawindow listenertemplate.jde-gen-listener-mouse-template Autocode Definesamouselistenertemplate.

jde-gen-inner-class-template Autocode Definesa templatefor creatingaclassinsideanotherclassor insideanexistingsourcebuffer.jde-gen-code-templates Autocode Specifiesavailablecodetemplates.

See

� CustomizingStandardTemplatesfor informationon how to customizetemplatesprovidedby theJDE.

� CreatingCustomTemplatesfor informationon how to createtemplatesfrom scratch.

15

1.5.4 Customizing Templates

You cancustomizetheJDE’sstandardcodetemplates,usingtheEmacscustomizationfeature.

To customizeanautocodetemplate:

1. SelectJDE- � Options- � Autocode

TheJDEdisplaysacustomizationbuffer containingtheautocodetemplates.

2. Edit thetemplateto suit yourneeds.

The JDE usesthe templateformat definedby tempo.elto representclasstemplates.Eachtemplateconsistsof a list of strings,symbols,andfunctions,eachof which representscon-tent to be insertedsuccessively into the buffer at the currentpoint. The stringsrepresentfixedcontent.Thesymbolsandfunctionsrepresentvariablecontent.Seethedocstringforthefunctiontempo-define-templatefor moreinformation,including themeaningof specialsymbolssuchas’n � .

3. Selectthestatebuttonassociatedwith thetemplate.

A menupopsup with a list of optionsfor saving yourchanges.

4. Saveyourchanges.

SelectSave for Future Sessionsif you want your changesto apply to all projects. If youwant your changesto apply only to the currentprojects,selectSet for Curr ent Session.Then selectJDE- � Options- � Save Project to save your changesin the currentproject’sprojectfile.

1.5.5 CreatingTemplates

The JDE considersany command(interactive function) that insertscodeinto a buffer at pointto be a template. The JDE usesthe Emacstempolibrary to createbuilt-in templates.You canusetempoto createyour own, add-ontemplates(seebelow and the doc for the tempo-define-templatefor more information)or createtemplatesfrom scratch. In eithercase,onceyou havecreateda template,you can add it to the JDE’s lists of available codeand/orbuffer templates,using the JDE’s jde-gen-code-templatesand/or jde-gen-buffer-templatesvariables,respectively.Adding a templateto theselists enablesyou to invoke thetemplatesfrom theJDEmenus.Whenaddinga template,you needto specifya uniquetitle for the template. Thesetitles enableyouto specifythe templateswheninvoking them,usingthe JDE’s customcodetemplatecommands(Files-� JDE New-� Custom andJDE- � Generate-� Custom ). You canuseautocompletiontoenteratemplatetitle wheninvokingacustomcodegenerationcommand.Notethatyoucanspecifydifferentsetsof templatesfor differentprojects,by settingandsaving thetemplatelist variablesinprojectfiles. Seethefollowing sectionsfor moreinformation:

� Defininga TemplateandTemplateInsertionFunction

� RegisteringCustomTemplates

16

� AssigningKeysTo Templates

Defining a Templateand TemplateInsertion Function

Thetempo-define-templatemacroenablesyou to definea templateanda functionthatinsertsthattemplateat the currentpoint in the currentbuffer. You specify the templateasa list oftemplateelementswhereeachelementis text, a specialsymbol,or a Lisp expression.Thefunction insertseachtext elementexactlyasspecifiedin thebuffer; it replacesspecialsymbolswith sometext (e.g.,userinput),andit replacesLisp expressionswith thetext thatresultsfrom evaluatingthem.

For example,thefollowing Lisp code

(tempo-define-template"foo" ;; template name

’("System.out.println(\"foo\"); ") ;;template definition"f" ;; abbreviation

"Inserts a print foo message") ;; template documentation

definesa templatefor Javacodethatalwaysprints“foo” to standardout:

System.out.println("foo");

NoticethatthetemplatedefinitionusestheLisp stringescapecharacterto specifythestring“foo”.This is necessarywhenyou wantto includequotedstringsin a templatedefinition.)

The sampleLisp form also definesan interactive templatefunction tempo-template-foo.Nowsupposeyou insertthesamplecodein your .emacsfile. After Emacsstartsup,wheneveryouenterthecommandM-x tempo-template-foo,Emacsinserts

System.out.println("foo");

at thecurrentpoint in yourJavasourcebuffer (or any buffer, tempodoesn’t care).

Theprecedingexampleis admittedlynot vary usefulbecauseit alwaysprints thesametext. Youcan createmore useful templates,using specialtempotemplatesymbolsand lisp forms. Thisapproach,for example,allows you to createa templatethat can print any user-definedtext tostandardout:

(tempo-define-template"debug" ;; template name

17

’("if (debug)" n> ;; insert new line plus indent"System.out.println("(p "Enter debug message:") ;; Prompts for debug message");")"d" ;; abbreviation

"Inserts a print debug message") ;; template documentation

Thetemplatefunctionproducedby this examplepromptsyou to enterthetext to beprintedwheninsertingthefunctioninto abuffer. In particular, it inserts

if (debug)System.out.println(DEBUG-MESSAG E);

whereDEBUG-MESSAGE is any text thatyou enter. For example,supposeyouenter

"Selected color = " + color

at theprompt.Thetemplatefunctioninserts

if (debug)System.out.println("Selected color = " + color);

at thecurrentpoint in thebuffer.

Seethedocumentationfor tempo-define-template(typec-h f tempo-define-template)for morein-formationoncreatingtemplates.RegisteringCustomTemplates

You canregistertemplatesthat you createwith the JDE.Whenyou registera templatewith theJDE,it appearsamongthelist of templatesthatyou canselectwhenyou selectJDE- � Generate-� Other... . You registera templateby customizingtheJDEvariablejde-gen-code-templates.Thevalueof this variableis a list of the templatefunctionsthat theJDEcommandJDE- � Generate-� Other... caninvoke. To registera customtemplate,addits nameto the list. For example,thefollowing screenshows thecustomizationbuffer forjde-gen-code-templatesafterit hasbeencustomizedto includethetemplatedefinedin thepreviousexample.

18

To inserta templatethatyou haveregistered

1. SelectJDE- � Generate-� Other...

TheJDEdisplaystheprompt

Entertemplate:

in theminibuffer.

2. Enterthetemplate’snameandpressRETURN

or,

presstheTAB key to displaya list of templatesin acompletionbuffer:

19

Selectthetemplateyouwantby double-clickingits name.

AssigningKeysto Templates

Youcanassigntemplatesto keyboardkeysto speeduseof frequentlyusedtemplates.For example,insertthis form

(global-set-key [f9] ’jde-gen-to-string-method)

in your .emacsfile to assignthe F9 function key to the JDE templatethat generatesa skeletontoStringmethod.

1.6 Compiling Java Programs

The jde-compilecommand(JDE- � Compile , C-c C-v C-c) compilestheJava sourcefile in thecurrentbuffer, usingjavac, theJava compilerprovidedby theJDK, or anothercompilerthatyouspecify(seeSpecifyinga Compiler). Thecompilecommanddisplaysthe outputof thecompilerin a separatecompilationbuffer. If a compilationbuffer doesnot exist, the compilecommandcreatesthebuffer; otherwise,it reusestheexisting compileoutputbuffer. Thecompilationbufferoperatesin compilation-mode,astandardEmacsbuffer mode.Thismodegreatlysimplify locatingcompilationerrorsin theJava sourcecode.For example,to find theline thatcausea compilationerror, simply click theerrormessagein thecompilationbuffer.

20

TheJDEusestheEmacscommandstart-process-shell-commandto launchaJavacompileprocess.Thiscommandin turn usestheequivalentof

SHELL COMMAND SWITCH javacOPTIONSBUFFER NAME.java

to launchthecompileprocesswhereSHELL is thecommandshellspecifiedby theEmacsvariableshell-file-nameand COMMAND SWITCH is the valueof the Emacsvariableshell-command-switch. You mustsetthesevariablesto becompatiblein your .emacsfile. For example,if you setshell-file-nameto bash,you mustsetshell-command-switchto -c, the commandswitch usedbybash.

NoteCompileprocessesaretheonly processeslaunchedby JDE,usingacommandshell.TheJDEusestheEmacscommandstart-processto launchall otherprocesses,e.g.,java, jdb, andJDEbugprocesses.The start-processlaunchesprocessesas subprocessesof Emacs,without doing anywild-cardexpansionor environmentvariablesubstitutionof command-linearguments.

1.6.1 Compilation Options

TheJDEallowsyou to specifycompilationoptionsby settingcompilationvariables.Youmustusethe Emacscustomizationfeatureor, if available,JDE functionsto setcompilationvariables.Tousethecustomizationfeature,selectOptions- � Compile from theJDE menu. (SeeConfiguringtheJDEfor moreinformationonusingthecustomizationfeature).To savethecompilationsettingsin theprojectfile (seeUsingProjectFiles)for thecurrentsourcebuffer, selectOptions- � UpdateProject from theJDE menu.SettingCompile Options Interacti vely

If you set the customizationvariablejde-read-compile-args to a non-nil value,the JDE compilecommandpromptsyou to entercompilationoptionsin theminibuffer. It appendstheoptionsthatyou enterto theoptionsspecifiedvia customizationvariables.TheJDEsavestheargumentsthatyouenterin aminibuffer historylist. Youcanrecallpreviouslyenteredoptionsby pressingtheupor down arrowson yourkeyboard.

Note: TheJDEusesthevaluesof theJDEcustomizationvariablesto setthecompiler’scommand-line option switches. The JDE assumesthat the compiler you are using (specifiedby the cus-tomizationvariablejde-compiler)hasthesamesetof command-lineswitchesasthelatestversionof javac, thecompilersuppliedwith JavaSoft’s JDK. If thecommand-lineswitch for a particularoption supportedby the compiler your are using is not the sameas that specifiedby the latestversionof javac, you mustusethe variablejde-compile-option-command-line-args to selecttheoption.CustomizationVariables

Thefollowing tablelists theJDEcompilationvariablesandthefunctionsusedto setthem.

NameGroup Usagejde-compilerProjectSpecifiesthecompiler(javac,by default) to useto compilethecodein thecurrentsourcebuffer. Thecommandjde-set-compilersetsthebuffer-local valueof this option. jde-compile-option-command-line-argsCompileSpecifiesastringof command-lineargumentsto bepassedto thecompiler. jde-global-classpathProjectSpecifyclasspathsfor compile,run,anddebugcommands. jde-read-compile-argsProjectSpecifywhetherto readcompileoptionsfrom theminibuffer. jde-compile-option-classpathCompileSpecifiestheclasspathfor compilecommand.If set,this variableoverridesjde-global-classpath. jde-compile-option-sourcepathCompileSpecifiesthepathof sourcefiles for classesrequiredto compilethecurrentclass. jde-quote-classpathProjectQuotetheclasspathargument. jde-compile-option-directoryCompileSpecifiesthedirectoryinto which to placethecompiledclass. jde-compile-option-deprecationCompileWarnof useor overrideof adeprecatedmemberor class jde-compile-option-debugCompileGenerateinformationaboutlocal variablesfor debug tools. jde-compile-option-optimizeCompileDirectsthecompilerto try to generatefastercode. jde-compile-option-dependCompileAnalyzedependencies. jde-compile-option-depend-switchCompileCommandline switchthatcausesthecompilerto analyzedependencies. jde-compile-option-vm-argsCompileSpecifycommand-lineargumentsfor Java interpreterusedto run thecompiler. jde-compile-option-verbose-pathCompilePrintverbosemessages. jde-compile-option-verboseCompileListdirectoriessearchedto compilecurrentclass. jde-compile-option-nowarnCompileTurnoff warnings. jde-compile-option-encodingCompileSpecifythesourcefile encodingname,suchasEUCJIS SJIS. jde-compile-option-targetCompileGeneratecodecompatiblewith aspecifiedvm version. jde-compile-option-bootclasspathCompileSpecifyclasspathof standardlibrariesfor targetvm. jde-compile-option-bootclasspathCompileSpecifypathof directoriescontainingextensionsfor targetvm.

21

1.7 Building Java Applications

The JDE- � Build commandbuilds or rebuilds an application.This commandhastwo operatingmodes:java andmake. In java mode,this commandusesjavac’s built-in make (-depend)facilityto rebuild a project. In make mode, this commandusesa user-specifiedmake utility, suchasGNU make, to rebuild a project. SeeSampleMakefile for anexampleof a makefile for buildinga Java project. JDE configurationvariablescontrol which modeis used. In particular, if thevariablejde-build-use-make is non-nil, this commandinvokesthemake programspecifiedby thevariablejde-make-program.If thevariablejde-make-argsis anon-emptystring,this functionusesits contentsto invokemake;otherwise,it promptsyouto entercommand-lineargumentsfor make.If jde-build-use-makeis nil, this functioninvokesjavaconthesourcefile for theclassspecifiedbyjde-run-app-class,with the-dependoption. This causesjavac to recompileall missingor out-of-datefiles requiredto run theapplication’s mainclass.JDEfindsthesourcefor your application’smainclassby searchingthedirectoriesspecifiedby jde-db-source-directories.Thus,you mustsetthis variableto usetheJavabuild mode.

1.7.1 Build Options

Thefollowing tablesummarizestheusageof thebuild configurationvariables.

NameGroupUsagejde-build-use-makeProjectAnon-nil valuescausestheJDEto usea makeutility (specifiedby jde-make-program)to executetheJDE- Build command.A nil valuescausestheJDEto usejavacwith the-dependoptionto executetheJDE- Build command. jde-make-programProjectSpecifiesthenameof themakeutility usedto executetheJDE- Build command.Thedefault valuesis make. jde-make-argsProjectSpecifiesastringof command-linearguments(for example,“-f mymakefileall”) to bepassedto themakeutility usedto executetheJDE- Build command.If thenull string(“”), theJDEpromptstheuserto enterthecommand-lineargumentsin theminibuffer.

1.7.2 SampleMakefile

Thefollowing is asamplemakefile thatyoucanuseasamodelfor creatingmakefilesto build Javaprojects.

JDK = d:/jdk1.2/lib/classes.zipJMATH = d:/jmath/srcCLASSPATH = $(JMATH);$(JDK)COMPILER= javacVM = javaCOPTIONS= -g -deprecationROPTIONS=

CLASSES= Test.class�JMathError.class�JMathException.class�LinearSystem.class

.SUFFIXES:.java .class

all : $(CLASSES)

22

# Rebuild (if necessary)andrun theJMathtestsuite.run: $(CLASSES)$(VM) -classpath“$(CLASSPATH)” jmath.Test

# Removeall classfiles from theprojectdirectory.clean:rm *.class

# Implicit rule for makingJavaclassfiles from Java# sourcefiles..java.class:$(COMPILER)$(COPTIONS)-classpath“$(CLASSPATH)” $?

1.8 Running Java Applications

TheJDEallows you to run a Java applicationasanEmacssubprocess.You canrun multiple ap-plicationsconcurrently, but only oneinstanceof eachapplicationata time. TheJDEdisplayseachapplication’s standardanderroroutputin anEmacscommandinterface(comint)buffer. You caninteractwith applicationsthat acceptcommandline input via the comint buffer. Wheninteract-ing with anapplication,you canuseany of comint-mode’s extensivesetof command-linehistorycommandsto speedinteraction.To run anapplication,enter

M-x jde-run

or selectJava- � Run App on the Emacsmenubaror type C-c C-v C-r. Specifying a StartupDir ectory

TheJDEcanstartan applicationfrom any directorythat you specify. By default, the JDEstartsan applicationfrom the default directory of the currentsourcebuffer. The default directory ofthe currentsourcebuffer is the directorycontainingthe sourcefile displayedin the buffer. Youcanspecifyanotherdirectoryas the startupdirectoryby settingthe JDE customizationvariablejde-run-working-directory.

To setthis variable,

1. Displayits customizationpanel.

Youcando this by typing

M-x customize-variablejde-run-working-directory

or selectingOptions- � Project from the JDE menuto display the project customizationpanelandsearchingthis panelfor jde-run-working-directory.

23

2. Entertheworkingdirectoryin thevariable’sedit field.

3. Save thenew setting.

To savetheeditedbindings,right click the[State] buttonandchooseSetfor current sessionif you want thesettingsto applyonly to thecurrentprojector Save for futur e sessions ifyouwantthesettingsto applyto all projects.In eithercase,youshouldsavethenew settingsin you projectfile if your projecthasa projectfile. To save thenew settingsin your projectfile, switchto a sourcebuffer andchooseOptions- � SaveProject from theJDE menu.

1.8.1 SettingVM Command-Line Ar guments

If you set the customizationvariablejde-run-read-vm-args to a non-nil value, the JDE compilecommandpromptsyou to entervirtual machineoptionsin theminibuffer. It appendstheoptionsthatyou enterto theoptionsspecifiedvia customizationvariables.TheJDEsavestheargumentsthat you enterin a minibuffer history list. You canrecall previously enteredoptionsby pressingtheupor down arrowson yourkeyboard.

1.8.2 SettingCommand-Line Application Ar guments

If you set the customizationvariablejde-run-read-app-args to a non-nil value, the JDE compilecommandpromptsyou to entercommand-lineapplicationargumentsin theminibuffer. It appendstheoptionsthatyouenterto theargumentsspecifiedvia thecustomizationvariablejde-run-option-application-args.TheJDEsavestheargumentsthatyou enterin a minibuffer historylist. You canrecallpreviouslyenteredoptionsby pressingtheupor down arrowson your keyboard.

1.8.3 Run CustomizationVariables

The JDE allows you to specifyrun-timeoptionsby settingrun variables.You canusetheEmacscustomizationfeatureto set run-time variablesinteractively. To usethe customizationfeature,selectProject- � Options- � Run from theJDE menu. (SeeConfiguringtheJDE for moreinfor-mationonusingthecustomizationfeature).To savethecompilationsettingsin theprojectfile (seeUsing ProjectFiles) for the currentsourcebuffer, selectProject- � Project File- � Save Projectfrom theJDE menu.

24

Thefollowing tablelists theJDErun-timevariablesandthefunctionsusedto setthem.

Variable Group Usagejde-run-mode-hook Project List of hookfunctionsrunby jde-run-mode.

jde-run-working-directory Project Startupdirectoryfor runningor debuggingJavaapplications.jde-run-application-class Project Nameof theJavaclassto run. Thecommandjde-run-set-appsetsthebuffer-local valueof this variable.

jde-run-java-vm Project SpecifyJava interpreterfor non-Windowsplatforms.Thecommandjde-run-set-vmsetsthebuffer-local valueof this variable.jde-run-java-vm-w Project SpecifyJava interpreterfor Windowsplatforms.Thecommandjde-run-set-vm-wsetsthebuffer-local valueof this variable.jde-global-classpath Project Specifyclasspathsfor compile,run,anddebug commands.Thecommandjde-set-global-classpathsetsthebuffer-local valueof this variable.

jde-run-classic-mode-vm Project SpecifiesthattheJDEshouldrun theJDK’sclassicversionof theJavavirtual machine(asopposedto theHotSpotversion).Thisoptionappliesonly to versionsof theJDK thatincludebothaclassicanda HotSpotvm.jde-run-read-vm-args Project Specifieswhetherto readvm argumentsfrom theminibuffer.

jde-run-option-classpath Run Specifiestheclasspathfor theJava interpreter. Thisoptionoverridesthejde-global-classpathoption.jde-run-option-verbose Run Print messagesabouttherunningprocess.

jde-run-option-properties Run Specifypropertyvalues.jde-run-option-heap-size Run Specifytheinitial andmaximumsizeof theinterpreterheap.jde-run-option-stack-size Run Specifysizeof theC andJavastacks.jde-run-option-garbage-

collection Run Specifygarbagecollectionoptions.jde-run-option-java-profile Run EnableJavaprofiling.jde-run-option-heap-profile Run Outputheapprofiling data.

jde-run-option-verify Run Verify classes.jde-run-option-vm-args Run Specifycommand-lineargumentsto bepassedto theJavavm. Thecommandjde-run-set-argssetsthebuffer-local valueof this variable.

jde-run-option-application-args Run Specifycommand-lineargumentsto passto theapplication.Thecommandjde-run-set-app-argssetsthebuffer-local valueof this variable.

1.9 Working with Applets

TheJDEprovidesspecializedcommandsfor runninganddebuggingapplets.

1.9.1 Running Applets

To runanapplet:

1. Opentheapplet’ssourcefile in abuffer.

2. ChooseJDE- � Run Applet .

The JDE searchesfor an html file in the directory containingthe appletsourcefile anddisplaysthefirst file it finds,usingyour system’sdefault browser. If theJDEcannotfind anhtml pagein theapplet’ssourcefile directory, it signalsanerrorby default.

The JDE- � Run Applet commandassumesby default that the directorycontainingthe applet’ssourcealsocontainsanhtml pagefor testingthatapplet.If this is not truein your case,you have

25

two options.You caneitherspecifythepathof theappletfile via theJDEcustomizationvariablejde-run-applet-docor you canusethe jde-run-appletcommandto run your applet. If the jde-run-applet-docvariableis notanull string,JDE- � Run Applet displaysthedocumentthatthevariablespecifiesinsteadof searchingthe sourcefile directory for a documentto display. The jde-run-appletcommandpromptsyou to enterin theminibuffer thepathof anhtml file to display. If youenternothing,thecommanddefaultsto thebehavior of JDE- � Run Applet .

The run commandschoosesthe viewer asfollows. If jde-run-applet-viewer is a null string (thedefault) or browse-url,theJDEusesbrowse-urlto launchtheappletdoc in your system’s defaultbrowser. Otherwise,the menucommandusescomint to launchthe viewer (e.g., appletviewer)specifiedby jde-run-applet-viewer.

1.9.2 DebuggingApplets

To debuganapplet:

1. Opentheapplet’ssourcefile in abuffer.

2. ChooseJDE- � Debug Applet .

TheJDEsearchesfor anhtml file in thedirectorycontainingtheappletsourcefile. If theJDEcannotfind anhtml pagein theapplet’s sourcefile directory, it signalsanerrorby default.Otherwise,it runsappletviewer in debug modeon thefirst file thatit finds.

TheEmacswindow splitsinto two panes.

The top paneshows theapplet’s sourcefile with thedebug cursorpointing to thefirst line of theapplet’s init file. Thebottompanedisplaysthedebugger’s commandline interface.You cannowsetbreakpoints,single-step,or continuerunningtheapplet.SeeDebuggingApplicationsfor moreinformation.

If you want to specifythedocumentto beusedto testtheapplet,customizethevariablejde-run-applet-docor executeM-x jde-db-applet.Thiscommandpromptsyou to enterthetestdocument’sname.

1.9.3 Applet CustomizationVariables

The JDE allows you to specify run-time optionsfor appletsby settingJDE configurationvari-ables.You canusethe Emacscustomizationfeatureto setappletrun-timevariablesinteractively.To usethe customizationfeature,selectOptions- � Run from the JDE menu. (SeeConfiguringthe JDE for moreinformationon usingthe customizationfeature). In somecases,the JDE alsoprovides functionsfor settingthe buffer-local valuesof the compilationvariables. To save thecompilationsettingsin theprojectfile (seeUsingProjectFiles)for thecurrentsourcebuffer, selectOptions- � UpdateProject from theJDE menu.

26

Thefollowing tablelists theJDEappletrun-timevariablesandthefunctionsusedto setthem.

Variable Group Usagejde-run-applet-viewer Project Specifynameof viewer to useto displaypagecontainingtheapplet.Thecommandjde-run-set-applet-viewersetsthebuffer-local valueof this variable.

jde-run-applet-doc Project Specifynameof documentcontainingappletto beviewed.Thecommandjde-run-set-applet-docsetsthebuffer-local valueof this variable.

1.10

DebuggingApplications

TheJDEprovidestwo optionsfor debuggingJavaapplications.

� An Emacsinterfaceto jdb, thecommand-linedebuggerthat comeswith theJDK. SeeDe-buggingwith jdb for moreinformation.

� JDEbug, a Java debuggerdevelopedspecificallyfor usewith the JDE.SeeJDEbug User’sGuidefor moreinformation.

JDEbugprovidesmoredebuggingfeaturesbut requiresaJDK 1.2or highervm. Youmustusejdbto debug applicationsrunningon earliervms.

1.11 Settinga Global Classpath

TheJDEallows you to definea classpaththatappliesto compiling,running,anddebuggingJavacode. You definethis classpathby customizingthe jde-global-classpathoption. To display acustomizationbuffer for this variable,selectJDE- � Project- � Options- � General or enterM-xcustomize-variablejde-global-classpath.

NoteDo notmakethemistakeof settingjde-global-classpaththewayyousetthe-classpathswitchof theJavavm. Thevalueof jde-global-classpathis a list of strings,eachof whichspecifiesapath.Whenstartinga programthat requiresthe-classpathswitch,suchasjavac, theJDEconvertsthislist to astringconsistingof pathsseparatedby asemicolonor colon.

Youcanalsodefineseparateclasspathsfor compile,run,anddebugoperationsby customizingthevariablesjde-compile-option-classpath,or jde-run-option-classpath,jde-debug-option-classpath,respectively. If you set any of thesevariables,the variableoverridesthe valuedefinedby jde-global-classpathfor theoperationto which thevariableapplies.

1.12 UsingProject Files

A projectfile is a Lisp file that theJDEloadsandevaluateswhenever you opena Java sourcefilebelongingto a specificproject. Projectfiles allow you to save andrestoreproject-specificJDE

27

configurations.For example,you canusea projectfile to setthevalueof thejde-global-classpathvariableto a project-specificclasspathautomaticallywhenever you load a file belongingto thatproject.

1.12.1 How the JDE Finds Project Files

To simplify thetaskof findingprojectfiles, theJDEmakestwo assumptions.First, it assumesthatall Javasourcefilesrelatingto aparticularprojectlivein asingledirectorytree.Second,it assumesthatall projectfiles have thesamefile name.Thenameassumedby default is prj.el. You canusetheJDE configurationvariablejde-project-file-nameto specifyanothername.Whenyou openaJava sourcefile, the JDE looks for a projectfile in the directorycontainingthe sourcefile. If itcannotfind a projectfile in thesourcefile directory, it searchesup thedirectorytreeuntil it findsa projectfile or reachestheroot of thedirectorytree. If theJDEfindsa projectfile, it loadsandevaluatesthecontentsof thefile asthe laststepin creatingthebuffer containingtheJava sourcefile.

1.12.2 Project File Contents

A projectfile cancontainany Lisp codethatcanbeevaluatedcorrectlyasthelaststepin creatinga Java sourcebuffer. For example,a project file can containcodethat setsthe value of JDEconfigurationvariables.In general,a projectfile cancontainany codethatcouldbeimplementedasa jde-modehookfunction. In fact,you canthink of aprojectfile asa project-specificjde-modehookfunction.

1.12.3 Creatinga Project File

Theeasiestway to createa projectfile is to usethe jde-save-projectcommand(JDE- � Options-� Save Project ). This commandsavesthe currentvaluesof all the JDE configurationvariablesin the projectfile for the selectedJava buffer. (To be precise,the commandinsertsLisp codeintheprojectfile thatrestoresthecurrentsettingsof theconfigurationvariables;if suchcodealreadyexists in thefile, it replacesit with updatedcode.)If theprojectfile doesnot exist, thecommandcreatestheprojectfile. Thus,to createaprojectfile thatsetsJDEconfigurationvariablesto project-specificvalues:

1. Openany sourcefile belongingto theproject.

2. Setthevaluesof theJDEconfigurationvariablesto theappropriatevaluesfor theprojecttowhich thesourcefile belongs.

3. SeeConfiguringtheJDEfor informationon how to setthevaluesof theJDEconfigurationvariables.

28

4. SelectOptions- � Save Project from theJDE menuto createa projectfile in thedirectorycontainingthesourcefile.

Onceyou have createdtheprojectfile, you caninsertadditionalconfigurationcodeinto thefile ifdesired.Note that the jde-save-projectcommandeditsratherthanreplacesexisting projectfiles.Thus,you canusethecommandto updateconfigurationvariablesettingswithout disturbinganyotherconfigurationcodethatyou have insertedmanuallyinto theprojectfile.

1.13 Displaying Java Documentation

The JDE providescommandsfor displayingthe JDK API documentationandcontext-sensitivehelpfor classes.

1.13.1 Browsing JDK Documentation

Thejde-browse-jdk-doccommand(JDE- � BrowseJDK Doc , C-c C-v C-n) openstheJDK doc-umentationin a browser. By default, this commanddisplaysthe JDK documentationpageatJavaSoft’s web site. To displaya differentcopy, setthevariablejde-jdk-doc-urlto theurl of theindex pageof thecopy youwantto bedisplayed.

1.13.2 Context-Sensitive ClassHelp

TheJDK providescontext-sensitive help for Java classes.To usethis facility, you mustfirst cus-tomizethevariablejde-help-docsetsto specifythelocationof classdocumentationonyoursystem.TheJDEclasshelpfacility supportsjavadocdocumentationbydefaultbut it workswith othertypesof documentationaswell.

Onceyou havespecifiedthelocationof classdocumentationon your system,you cangethelpfortheclassat point in thecurrentbuffer by selectHelp- � Symbolat Point from theJDE menu.

1.14 BrowsingSourceCode

TheJDEprovidesthefollowing facilitiesfor browsingJavasourcecode:

� jde-show-class-sourcecommand

� Classesindex menu

� Speedbar

� Etags

29

1.14.1 jde-show-class-sourceCommand

The jde-show-class-sourcecommand(C-c C-v C-y) finds andopensthe Java sourcefile for theclasswhosequalifiedor unqualifiednameappearsat point. If morethanoneclasswith thesamenameexistson jde-global-classpath,this commandpromptsyou to selectoneof theclasses.Thefollowing conditionsmustbetruefor this commandto work. First, a classfile for this classmustexist on thecclasspathspecifiedby jde-global-classpath.Secondly, thesourcefor theclassmustexist ononeof thepathsspecifiedby jde-db-source-directories.ThiscommandusestheBeanshellto determinethefully qualifiednameof theclassto befound. It startstheBeanshellif necessary.Thus,thecommandmayrespondsomewhatslowly thefirst timeyou it in asession.

1.14.2 ClassesIndex Menu

TheClassesindex menuappearsby default in theEmacsmenubarwheneveraJavasourcebuffer isactive. Themenuconsistsof acascadinglist of all classes,methods,fields,andimportsdefinedinthecurrentbuffer plusthepackageto which thecurrentbuffer belongs.Selectingany item scrollsthebuffer to thestatementthatdefinestheitem.

Thetop-level menucontainsanentryfor eacheachclassdefinedby theactive buffer followedbyentriesfor theimportsandpackageof thecurrentbuffer. Selectingtheentryfor a classdisplaysasubmenulisting theinnerclasses,methods,andfieldsdefinedby theclass.Selectingtheentryforan innerclassdisplaysanothersubmenufor thatclass,andsoon. Selectingthe imports entryonthetop-level menudisplaysa submenulisting all theclassesandpackagesimportedby theactivebuffer. SpecialIndex Entries

30

Theindex menuincludesthefollowing specialindex entries:

� *Rescan*

Selectingthis item causestheJDEto rebuild theindex menu.You shouldrebuild themenuwheneveryouedit thebuffer.

� *classdef*

Selectingthis item takesyou to the startof the definition of the classon whosesubmenuit appears.Turn the variablejde-imenu-include-classdefoff to suppressinclusionof theseitemsin themenu.

Alphabetizing the ClassesMenu

By default theClassesmenulistsmethodsandfieldsin theorderin whichtheactivebuffer definesthem. Use the variablejde-imenu-sortto customizethe menuto list methodsandfields alpha-betically in eitherascendingor descendingorder. SuppressingMethod Signaturesand FieldTypes

By default theClassesmenudisplaysthesignaturesof methodsandthetypesof fieldsdisplayedin theactive buffer. Themethodsignaturesenableyou to distinguishoverloadedmethodnames.Themenucanalsodisplaythenamesof methodsandfieldswithout signaturesandtypes.Usethevariablejde-imenu-include-signatureto turn signatureandtype displayoff or on. Disabling theClassesMenu

Setthevariablejde-imenu-enableoff to disabletheClassesmenu.Whendisabled,themenudoesnotappearin theEmacsmenubar.

1.14.3 Using the Speedbar

To displaythespeedbar, selectSpeedbarfrom theJDE menu.Thespeedbaropensin a separateframe.

31

The speedbardisplaysa list of the files and subdirectoriesin the directory containingthe filedisplayedin thecurrentbuffer. Thespeedbarhighlightsthefile displayedin thecurrentbuffer.

Click on theexpand(+) buttonin front of any file. Thenodefor thefile expands

to show up to threeentries,dependingon thecontentsof thesourcefile. Package

This itemexpandsto show thepackageto which thefile belongs.

Clicking on thepackagescrollsthebuffer to thecorrespondingpackagedeclaration.Types

This itemexpandsto show theclassesin theselectedfile.

32

Eachclassexpandsto show the constructors,methods,fields, and inner classesdefinedby theclassandthe class’s parent,if any. Inner classesalsoexpandandtheir inner classes,andso on.The constructorsandmethodsexpandto show argumentsandargumenttypesandreturn types.Fieldsexpandto show their type.

Clicking onany class,innerclass,method,constructor, or field scrollsthebuffer to show thatitem.DependenciesThis itemexpandsto show theclassesandpackagesimportedby thecurrentsourcefile.

Click onclassor packageto scroll thebuffer to thecorrespondingimportstatement.Updating theSpeedbar

If you make changesto a sourcebuffer, you mustupdatethespeedbarview to reflectthechanges.To updatethespeedbarview of abuffer:

33

1. Collapsethespeedbarview of thebuffer.

This is necessaryonly if thespeedbarview is expanded.To collapsethespeedbarview, clickthecollapsebutton(-) next to thebuffer’sfile namein thespeedbarview.

2. Hold theshift key down while clicking theexpandbutton(+) next to thebuffer’snamein thespeedbarview.

1.14.4 Tags

To usethe etagsfacility, you mustfirst constructa TAGS file that indexesevery symbol in yoursourcecode.TheJDEpackagecontainstwo shellscriptsthatyoucanuseto tagyoursourcecode,onefor cshshellsandtheotherfor bash.Thebashversionis calledjtags;thecshversion,jtags.csh.TaggingJava SourceCode

To tagyour sourcecode,first copy theappropriateshellscript to a directoryin your Emacspath.Thenstarta shell (M-x shell). Changeto thetop-level directorycontainingyour sourcecodeandthenenterjtags.Thejtagsscripttagsevery .javafile in thecurrentdirectoryandin all descendantsof thecurrentdirectory, storingtheresultin a file calledTAGSin thetop-level directory. Findingthe Definition of a Symbol

To find thedefinitionof a symbol,put your cursoranywherein thesymbolandenterM .. Emacsrespondsby locatingandopening(if necessary)thefile containingthedefinitionandpositioningthepointat thedefinition.(Thefirst timeyou typeM ., Emacspromptsyou to loadtheTAGSfile.)

1.15 Customizing the JDE

ThissectiondescribesvariouswaysyoucancustomizetheJDE.

1.15.1 CustomizationVariables

JDE customizationvariablesallow you to specify compile, run, debug, options. You mustusecustomizationbuffersto setJDEcustomizationvariables(seetheEmacsonlinemanualfor infor-mationon thecustomizationfeature).

1.15.2 Settinga Variable

NoteYou cannotusesetqformsin your .emacsfile to setJDEvariables.You must usecustomize.Any valuessetvia setqformsareresetto theirdefaultvalues.To setaJDEcustomizationvariable:

1. Determinethenameof thevariableyou wantto customize.

Referto thesectionof this guidethatdocumentsthe featureyou want to customizefor thenameof thecorrespondingvariable.Or typeC-h v followedby theJDEgroupprefix (jde-) or subgroupprefix (e.g., jde-compile-option-,seeJDE CustomizationGroups). Emacs

34

displaysall variablesbelongingto theJDEgroupor subgroup.Youcanthenbrowsethis list,usingEmacssearch,completion,anddocumentationdisplaycommand,to find theapplicablevariable.

2. Displayacustomizationbuffer for thevariable.

If you know thenameof thevariable,theeasiestway to displaya customizationbuffer forthe variableis to selectHelp- � Customize-� SpecificOption... from the Emacsmenubaror typeM-x customize-variable.If you know thegroupto which thevariablebelongs(.e.g.,compileoptions),you can display the customizationbuffer for the group. This is usefulwhenyou want to customizeseveral relatedvariables.SeeJDECustomizationGroupsformoreinformation.

3. Edit thevaluefor thevariabledisplayedin thecustomizationbuffer.

4. Save thevaluefor thevariablein your .emacsor .prj file.

If you want the settingto apply to all projectsthat do not have a project file (seeUsingProjectFiles),you shouldsave thevariablein your .emacsfile. To save thevariablein your.emacsfile, selectSave for Future Sessionsfrom the State menufor the variablein thecustomizationbuffer.

If you want thesettingto applyonly to a particularproject,you shouldsave the settinginthe .prj file for thatproject. To do this, opena sourcefile from that project,selectSet forCurr ent Sessionfrom theStatemenufor thevariable,selectthesourcebuffer, andselectJDE- � Project- � Project Files-� Save (C-c C-v C-p) from theEmacsmenubar.

Note If a projectfile doesexist for theproject,theJDEwill promptyou to entera namefortheproject.It thencreatesaprojectfile for theprojectwith thenamethatyouenter.

1.15.3 JDE CustomizationGroups

TheJDEdefinesatop-level customizationgroup,theJDEGroup,for JDEcustomizationvariables.TheJDEGroupitself containsthefollowing subgroups:Compile Option Group

Specifiescompileoptionscorrespondingto thecommand-linearguments(e.g.,-d) acceptedby theJDK compiler, javac. Whenyou executetheJDEcompilecommand,theJDEusesthesettingsofthisgroupto constructa list of command-lineargumentsthatit passesto theJavacompilerthattheJDEusesto compileJava sourceprograms.Thecompileris itself anoptionthatyou canspecify(seetheProjectOptionGroup). You canspecifycommand-lineargumentsdirectly by settingthevalueof the jde-compile-option-command-line-argsvariable. You candisplaythe customizationbuffer for the CompileOption Groupby selectingProject- � Options- � Compile from the JDEmenu.Run Option Group

Specifiesrun-timeoptionscorrespondingto thecommand-linearguments(for example,-classpath)acceptedby theJDK virtual machine,java. Whenyou executetheJDE Runcommand,theJDEusesthe settingsof this group to constructa list of command-lineargumentsthat it passesto

35

the Java interpreterusedby the JDE to run applications. This group also containsoptionsforspecifyingnon-javacommand-linearguments(in caseyouwantto useaVM thatacceptsadifferentsetof argumentsthanjava does)andfor specifyingargumentsto bepassedto theapplication(asopposedto the virtual machineinterpretingthe application.) You candisplaythe customizationbuffer for the Run Option Group by selectingProject- � Options- � Run from the JDE menu.Debug Option Group

Specifiesrun-timeoptionscorrespondingto thecommand-linearguments(for example,-classpath)acceptedby theJDK debugger, jdb. jdb acceptsthesamecommand-lineargumentsasjava. How-ever, theJDEmaintainstwo parallelsetsof configurationvariablesfor theseprogramsin caseyouwantto useadifferentsetof optionsfor runningaprogramin debugmodethenyouusefor runningit normally. Whenyou executetheJDEDebug command,theJDEusesthesettingsof this groupto constructa list of command-lineargumentsthat it passesto theJavadebuggerusedby theJDEto runapplicationsin debugmode.Youcandisplaythecustomizationbuffer for theDebugOptionGroupby selectingProject- � Options- � Debug from theJDE menu.AutocodeGroup

Specifiestemplatesusedto generatecodeautomatically. GeneralOptions Group

Specifyall otherJDE options. You candisplaythe customizationbuffer for the GeneralOptionGroupby selectingProject- � Options- � General from theJDE menu.

1.16 Customizing jde-mode

TheJDEdefinesa majormode,namedjde-mode,for editingJava sourcefiles. This modederivesfrom thestandardEmacsJavasourceeditingmodejava-mode.In particular, it inheritsall thefunc-tionsandcustomizationvariablesdefinedby java-modeandaddsits own customizationvariables.Whenyou loadaJavasourcefile, EmacsrunsaJDEmodeinitialization functioncalledjde-mode.Thejde-modefunctionin turncallstheJavamodeintializationfunction,java-mode.Thelastthingthatjde-modedoesbeforereturningis to call aJDEmodefunction,if it exists.YoucancustomizetheJDEby defininga JDEmodehookfunction in your .emacsfile. Thefollowing is anexampleof how to do this:

(defunmy-jde-mode-hook()(message“my-jde-mode-hookfunctionexecuted”))(add-hook’jde-mode-hook’my-jde-mode-hook)

Theprecedingexampledefinesa JDEmodehookfunctionnamedmy-jde-mode-hookandaddsitto thelist of JDEmodehookfunctions,usingtheEmacsLisp functionadd-hook.Now, wheneveryou opena Java sourcefile, jde-modeinvokesthe function my-jde-mode-hook.Of course,thehookfunctiondefinedin this exampleis trivial. A real-world examplemight do somethingmoreuseful,suchassettingacustomindentationstyle.

1.16.1 CustomizingKeyBindings

A key bindingestablishesanequivalencebetweena keystrokeor a sequenceof keystrokesandaninteractive Lisp function. The keystroke or keystroke combinationcausesEmacsto executethe

36

function to which the keystroke (combination)is bound. For example,the JDE by default bindsthekeystrokeC-cC-v C-c to thefunctionjde-compile.YoucanusetheJDEcustomizationfacilityto changethe standardJDE bindingsor createbindingsfor functionsthat do not have defaultbindings.

To customizekey bindings:

1. Openabuffer on theJDEcustomizationvariablejde-key-bindings.

2. Youcando this by typing

(a) M-x customize-variablejde-key-bindings

orbyselectingJDE- � Options- � ProjectandsearchingtheresultingJDEprojectcustomiza-tion buffer for jde-key-bindings.

Thekey bindingspanellookslike this:

3. Edit thebuffer to specifyalteredor new bindings.

4. For example,to adda binding,right click the [INS] button,thenenterthekey stroke in theKey field and the interactive function (command)to which it is boundin the Commandfield.

37

5. Save theeditedbindings

6. To savetheeditedbindings,right click the[State] buttonandchooseSetfor current sessionif you want thesettingsto applyonly to thecurrentprojector Save for futur e sessions ifyouwantthesettingsto applyto all projects.In eithercase,youshouldsavethenew settingsin you projectfile if your projecthasa projectfile. To save thenew settingsin your projectfile, switchto a sourcebuffer andchooseOptions- � SaveProject from theJDE menu.

38