JACK® INTELLIGENT AGENTS v5.4 This release fixes several issues related to Windows Vista and the JACK installation process. When tracing graphical plans, the condition methods are no longer displayed by default. (jack54b onwards) JACK® INTELLIGENT AGENTS v5.3b In the JDE, "Edit as JACK File" now allows comments at the end of the type definition and even at the end of the file. It gets stored in a special Java code block called %TRAILING_CODE. The "Edit as JACK File" operation now always edits a temporary file. You will need to regenerate the JACK files if you wish to compile the JACK code from outside the JDE. If you wish to edit the JACK code "in place", you can do it from outside the JDE (see new option below). JACOB now supports bytes (8 bit integers) as a low level data type. Beliefsets can now have "byte" values as fields. Changes to support the latest version of CoJACK. There is a new option (set via Preferences/File Editor) that allows the JDE to automatically detect (and possibly import) changes made to JACK code from outside the JDE. When a changed JACK file is detected, it behaves as if an Edit-as-JACK-file operation was performed on the file. WARNING: this is a BETA release of this feature. If you encounter any problems with this feature, please report it to jack-support@aosgrp.com. KNOWN LIMITATION: it is a bad idea to edit the same JACK code from inside the JDE and outside the JDE at the same time. An early version of this feature was present in JACK 5.2f -- see description of jack52f below for more details. JACK® INTELLIGENT AGENTS v5.2f Added the ability to edit JDE generated JACK code from outside the JDE and load it back in to the JDE in a similar way to the "Edit As JACK File" functionality. This is useful if you prefer to edit JACK code in textual form and want to use a more specialized IDE such as Eclipse, for example. However it works the same way with any text editor you care to use. Loading changes made to generated JACK files from outside the JDE can be done in a number of ways: 1. Reload the component (using contextual menu) 2. Load External Edits (from the File Menu) 3. Automatically by setting your preferences. If you have set your preferences to periodically check for changes to the generated JACK files, then any external edits will cause the component to become 'read-only' within the JDE. This should avoid conflicting edits from within the JDE. Currently some edits are still possible to 'read-only' components through the design tool. This will be fixed in a future release. There are still some minor issues with the periodic checking and the ability to avoid the dialogs that appear whenever an external change is made. Please report any problems with this feature (or any other problems) to jack-support@aosgrp.com.au JACK® INTELLIGENT AGENTS v5.2e Note: The JACK documentation is no longer bundled with the release. You may wish to download and install the separate documentation bundle or simply access the documentation from the internet. The JDE will automatically access the information from the internet if a local copy of the documentation has not been installed. JACK 5.2e contains minor bug fixes. JACK 5.2 contains an improved communications layer as well as various JACK and JACOB updates. JACK inter-process message size is no longer limited to the (machine-dependent) UDP packet size. A hook has been added to enable the user to supply their own derivation of java.net.DatagramSocket to a UDP portal. This may be useful for logging or for simulating unreliable networks. The JDE now accepts project files with file extension ".PRJ" as well as ".prj". Some minor enhancements and fixes. The JACK API documentation has been updated to include some methods that have previously been left out. Other parts of the API documentation have been improved. This release should be completely backwards compatible with earlier releases. If not, we'd like to hear about it at <mailto:jack-support@aosgrp.com>. JACK® INTELLIGENT AGENTS v5.1 Added ability to transport large JACK messages. No official releases made. JACK® INTELLIGENT AGENTS v5.0c JACK Version 5.0c contains updated manuals and practicals. The JACK API documentation has not been updated yet. The "New Project..." icon in the toolbar has now changed to reflect projects rather than looking like the "Add External Class..." icon. Spacing of the toolbar separator has changed on OS X. The spaces are now a little wider. JACK® INTELLIGENT AGENTS v5.0b This contains all patches to 5.0 since jack50a_009. Also: [5.0b Patch 005] Make sure Edit As Jack File does not add conflicting reasoning methods in a graphical plan. Remove graphical reasoning methods that don't actually exist from plans in JDE. Some cosmetic changes to JDE on Mac OS X. [5.0b Patch 004] Print the exception that occurred if the licence manager fails. [5.0b Patch 003] Some changes to kernel to fix possible race condition. Improved error message when agent constructor is passed a null pointer. [5.0b Patch 002] Minor changes to some internal APIs. [5.0b Patch 001] Fixes for type lookup in anonymous inner classes in JACK compiler. JACK® INTELLIGENT AGENTS v5.0a [5.0 Patch 009] Minor updates to JDE, mostly cosmetic. [5.0 Patch 008] Creating objects using the design palette or by importing could cause some exceptions in certain cases. Remove the open design diagram (if any) when a diagram is deleted from the project. [5.0 Patch 007] Creating new fields in an event using Edit as JACK File was incorrectly starting an auto-edit of the label. Avoid marking things as modified just by moving them into a different sub-folder. Changing the package of the underlying type of a Named Data caused some problems if the type was external. Changing the package of a component removes the corresponding JACK file to avoid later compilation errors due to duplicate files. However it was trying to remove the wrong filename. Some changes to the layout of the compiler utility Run tab. [5.0 Patch 006] Creating new Named Data was incorrectly starting an auto-edit of the name in the browser. Named Types could be written out with a package of "-" in the underlying type causing problems when loading. Changed the compiler to output fully qualified class names (for most things) to avoid possible ambiguities. The compiler still emits the import statements as before into the generated Java code to preserve backwards compatability. This can be changed by setting the jack.compiler.emit.imports=false property. Eventually this will become the default. Improved the fix for the compiler bug in Patch 005. Some updates to the example code supplied. [5.0 Patch 005] The component editing dialog did not display a "-" prefix for external components so you could not use it to convert an external component into an internal one. Fixed compiler bug which caused some complex expressions like "var = method( new Object( ( (Object[]) array )[n] ) );" to emit an error: aos.jack.jac.compile.NewExprNode has no resolveWithin method. [5.0 Patch 004] When a design was created using the toolbar or Entity menu in the JDE, any initial additions or changes were ignored. The design had to be closed and then re-opened to become active. [5.0 Patch 003] Make sure external named types are immediately converted to internal types. Fixed the syntax of the import statement automatically generated for role containers. Check against the current project to resolve any ambiguity when auto-fixing broken references. [5.0 Patch 002] When compiling MessageEvents into JACOB objects, don't silently remove any 'final' qualifier from static fields. If the field is not static or transient but marked as final, it is now treated as an error since JACOB has no way of assigning the 'final' field on the receiving side of the transportation. The user must use Java transport or remove the 'final' qualifier. Fixed bug in nested @maintenance violations. [5.0 Patch 001] Avoid warning about importing old version code when importing anything as 'stubs'. JACK® INTELLIGENT AGENTS v5.0a Note: JACK Version 5.0 still contains the JACK 4.1 documentation. The 5.0 documents will be not be available until May. All important changes are listed below. ------------- JACK Compiler ------------- Many improvements in the parsing of inner classes and other Java features. The @parallel statement (from JACK Teams) is now in the core language. Fixed race condition in named data creation when agents of the same type are created at the same time. Revised to a) discover multiple data statements, and b) allow use of "#imports data" and "#private data" as alternative for "#exports data". Also allows "#imports" with "#global" or "#agent", which weren't available before. The statement for "#posts event xxx yyy;" is now allowed in views, with the same usage as in beliefsets. Where possible, JACK message events are now transported in JACOB envelopes rather than Java-serialised envelopes by default. NOTE: If any event class no longer compiles, you can try adding a "#set transport java;" declaration to return to the old behaviour. The flag "-map=simpleteam" is recognised as a way to use the old simpleteam language. ------------ JACK Runtime ------------ Fixed memory leak - couldn't completely destroy/remove an Agent. Teams: Bug fix in revoking roles with belief propagation. Many property names which JACK recognises have been deprecated and replaced with a more consistent set of names. The old names will still work but will produce a warning to the terminal if present. Old Name => New Name ---------------------------------------------- PLUGINMAPFILE => jack.compiler.plugin.map jac.errors => jack.compiler.errors Jak.ID.* => jack.tracing.idisplay.* Jak.timeDilation => jack.run.timer.speedup Jak.DilationController => jack.run.timer.controller Jak.DilationController.* => jack.run.timer.controller.* Jak.PropertyFile => jack.property.file Jak.Args => jack.args Jak.exitOnError => jack.run.exit.on.error Jak.scheduler.nthreads => jack.run.nthreads Jak.scheduler.timeslice => jack.run.timeslice Jak.logging => jack.run.debug.options Jak.debugging => jack.run.debug.options Jak.debugfiles => jack.run.debug.agents Jak.CountLogs => jack.run.debug.show.count Jak.logFile => jack.run.debug.file Jak.logCtl => jack.run.debug.control Jak.logFormat => jack.run.debug.format Jak.Trace.ConfigFile => jack.plan.tracing.config Jak.Trace.Enabled => jack.plan.tracing.enabled Jak.Trace.AlwaysRaise => jack.plan.tracing.alwaysraise Jak.Trace.AlwaysRestore => jack.plan.tracing.alwaysrestore Jak.Trace.RunMode => jack.plan.tracing.runmode Jak.Trace.TraceTextual => jack.plan.tracing.tracetextual Jak.Trace.ListAllFacts => jack.plan.tracing.listallfacts Jak.Trace.DescriptiveMode => jack.plan.tracing.descriptivemode Jak.Trace.ZoomSlider.Show => jack.plan.tracing.zoomslider.show Jak.Trace.ZoomCombo.Show => jack.plan.tracing.zoomcombo.show Jak.Trace.ZoomSlider.ShowTickMarks => jack.plan.tracing.zoomslider.showTickMarks ---------------------------------------------- Added new boolean property "jack.run.repeatable" which if set, is equivalent to setting jack.run.timeslice=3600000 (i.e. 1 hour). This will avoid agent tasks being suspended and restarted at arbitrary points and is useful to ensure complete repeatability. ------------------------- JACK Communications (DCI) ------------------------- The default portal name can now be set using the "jack.portal.name" property. The default portal host can now be set using the "jack.portal.host" property. The default portal port can now be set using the "jack.portal.port" property. Fixed handling of "localhost" so that it does not resolve to the name of the external hostname or address but remains as is. An attempt to reconnect to a portal (after restarting a process, for example) did not always work on the first attempt. Added experimental property "dci.max.unackd" to only allow the given number of unacknowledged (UDP) messages to be queued on each portal before marking the portal as 'dormant' and delaying all new messages until some acknowledgements arrive. This is an untested and experimental feature. It may be useful in applications that have many processes exiting, restarting and reconnecting over slow communications links. ---------- JACK Teams ---------- Fixed postWhenFormed(...) to post the event if the team has already formed rather than to never post the event. JDE 5.0 - CHANGES SINCE JACK 4.1 -- JDE Known Issues NB: Graphical plan tracing cannot be used when the new Design tracing feature (see below) is being used. Attempting this will result in unexpected behaviour. When using Design Tracing, a '@subtask' does not currently cause the plan -> event transition to be displayed. When using "Edit as JACK File" comments added in front of JACK statements like "#uses ..." etc. are ignored. The only comments that are saved are those in front of the main class and in front of methods and other Java code. Dragging a node from the main project window onto the main desktop creates a new window for that node but tool-tips are not enabled for the new window. Note: the save file format has changed in 5.0 and loading a project will cause some warnings when the save files are loaded and automatically converted to the new format. -- Start Up If a non-existent file is passed on the command line e.g. "java aos.main.Jack nosuchfile", you are now given an option to create the project or locate the file. Added command line "-CJ" option to clean-out generated JACK files. This complements the existing "-J" and "-UJ" options. -- Title Bar Now contains the name of the project being edited/viewed as well as the application name and licence expiry date. -- Tool Tips Many of the tool tips have been improved. -- Keyboard Shortcuts The shortcut keys for the Plan Editor Palette and Design Palette have been changed to accommodate new features such as the Page Setup dialog. -- Menu Bar Previously contained [File], [Edit], [View], [Window] and [Help]. Now contains [File], [Edit], [View], [Entity], [Trace], [Tools], [Window] and [Help]. [File] menu now contains the "Convert Old Project" option. This provides a convenient way to update a project's save files to conform to the latest save format. [File] menu now contains the "Generate Project Report" option. This allows you to save all or parts of your project to a file in either simple text or XML format. This is useful for taking a JDE project and manipulating the data with custom tools. The report can also be printed directly from the JDE using the new "Page Setup" and "Print Project Report" menu options. Fixed the [File] -> [Copy/Move Project...] menu option to move/copy all designs and external components too. The dialog(s) for the Copy/Move operations have been simplified. [File] -> [Save Project] makes an attempt to remove unneeded save folders after components have been renamed. [File] -> [Save Project] sometimes left some components marked as still being changed and two saves were required. This is now fixed. [File] -> [Save Project] asks when any new save folders need to be created. When this happens you are given the option to "Create All" so that you will not be asked each time. Previously, this did not always work and you may have been asked many questions anyway. Generating JACK teams code using roles, now automatically generates the required import statements for the role containers. This applies to [File] -> [Update JACK Files] and [File] -> [Generate All JACK Files], as well as code generation from the command line using the "-J" option. [Edit] menu item "Preferences" has moved to the [Tools] menu except on Mac OS X where it is in the application menu. [View] menu now has an option "Show Tool Bar" for enabling and disabling the new toolbar feature (see below). [Window] menu no longer lists all the possible tool windows (e.g. "Design Palette") all the time. It is reserved for actual windows only. Popping up the tool windows has been moved to the new [Tools] menu. [Help] menu now contains options for looking at the supplied JACK documentation and for accessing the Agent Oriented Software home page on the internet, using the default browser. The "Paint_robot" example was added to the "Help -> Create Project From Example" sub-menu. The other examples have been improved with more design diagrams added etc. [Entity] menu provides a shorthand way of creating new entities. [Trace] menu allows you to connect to a running JACK application for the new Design Tracing feature (see below). The "Ping Agent" option can be used to see if the remote portal knows about a particular agent. [Tools] menu provides a way to display the various tool windows such as the "Compiler Utility", the "Design Palette", etc. On Windows and UNIX, this also contains the application's "Preferences" dialog. -- Toolbar The new toolbar can be enabled by setting the appropriate preference in the application's "Preferences". The toolbar can be dragged to other locations or even to its own window. It contains shortcuts to various functions. On the left of the toolbar: - New Project - Open Project - Save Project - Update (changed) JACK Files - Regenerate all JACK Files - Cut - Copy - Paste - Create New Design - Create New Agent - Create New Capability - Create New Plan - Create New Event - Create New Team (enabled when in Teams mode) - Create New Team Plan (enabled when in Teams mode) - Create New Role (enabled when in Teams mode) - Create New Named Role (enabled when in Teams mode) - Create New Named Data - Create New Beliefset - Create New View - Create New Team Data (enabled when in Teams mode) - Create New File - Show Preferences Dialog - Show Compiler Utility - Show Warnings/Error Log On the right of the toolbar: - Show Full Package Toggle - Show Documentation Nodes Toggle - Teams Mode Toggle -- Project Windows The structure of the main project window has not changed. The characters allowed in a project name are now restricted to the set of simple alphanumerics, underscore and dash. Any non-conforming project name will be automatically sanitised. Beliefsets, Views, TeamData etc. can now be dragged directly into the Named Data folder to create new Named Data entities. When events are dragged into plans (and similar gestures) there is now better automatic generation of new reference names to avoid clashes. Folders which allow their contents to be re-ordered can be sorted by their labels using the new "Sort Elements" option in the folder's contextual menu (i.e. using right-click). Removing sub-folders, automatically moving the contained entities up to the parent could cause some unexpected and seemingly unrelated bad behaviour. This has now been fixed. Removing things using selection and DELETE on the keyboard now removes them in order of highest numbered row first. Selecting rows that can't be deleted no longer complains during a (keyboard) delete operation. This is useful when many rows are selected at once for deletion. Holding the SHIFT key down when the DELETE key is pressed will avoid having to confirm the deletions. If top level components are deleted this way, the save files are removed immediately (actually they are renamed to <file>.bak). The default "Save Folder" under the main project item now is "gcode_<project>" where <project> is the project name. This makes it easier to keep several JDE projects in the same area. The location of some of the save files within the "Save Folder" has changed. In particular, Named Data referring to external components are always considered to be internal now and are not saved in the "ext-cache" folder any longer. -- Internal Text Editor The old internal text editing tool has been replaced. The new editor has search capability, multiple undo, line numbering, and syntax highlighting. The previous internal editor did not work under Mac OS X. -- Preferences + Project View Options A new option for sorting the contents of folders in the project window is now available. If a folder contains sub-folders, this option controls how they are sorted with respect to normal items in that folder. The sub-folders can be placed at the top of the list, the end of the list, or simply merged with the rest of the items, sorted by the labels. There is a new option to show the toolbar by default. There is some support for Makefiles and other automated building tools. A new option exists that tells the JDE to generate a new file whenever JACK files are generated or when any component has changed. If any files are changed and saved it is logged in "<project>.save.log" in the project folder. If any JACK files are generated it is logged in "<project>.gen.log" in the project folder. There is an option to warn if any external classes cannot be found in the CLASSPATH. The default "Save Folder" can now be specified here. The default is "gcode_%p" (where %p stands for the project name). + Text Editor Options The option to specify which characters should delimit words has been removed since it is built in to the new internal text editor. An option to display line numbers has been added. + Design Tool Options The option to use XOR for faster drawing has been removed. The drawing has been optimised and this option is no longer useful. Added option to use the full text editor to edit the text inside Note nodes. Added option to display only the first sentence of non-Note nodes when displaying a diagram in descriptive mode. Added option for descriptive mode to automatically reformat the text and resize the node so that all the text is visible (or the first sentence depending on the previous option). Added option for descriptive mode to set a limit on the number of characters displayed in the nodes. + Graphical Plans Options See Design Tool options above; exactly the same changes apply. + Fonts There are now options to set the fonts for designs and graphical plans. In addition, there is a powerful font chooser for selecting and setting these fonts. + Advanced Options (previously called "Debug") A new option to set the default browser has been added. This is not needed on Windows or Mac OS where the system default browser will be used automatically. -- Design Tool Design Tool objects and links now have a context menu available. The context menu on an entity allows you to "Edit...", "Edit as JACK File...", "Remove from Diagram" or "Remove from Project...". The context menu on a link allows you to remove or edit the link. The Design Tool has an extra button next to the 'print' button that allows you to export the diagram to a file that can be used in documents. JPEG and PNG file formats are currently supported. When objects on the diagram were close together, it was possible to select one (and it would be highlighted) but you could be editing the other object. This is now fixed. -- Graphical Plan Editor Graphical plan editor objects and links now have a context menu available that allows you to edit or remove the node or link. The Graphical Plan windows have an extra button next to the 'print' button that allows you to export the diagram to a file that can be used in documents. JPEG and PNG file formats are currently supported. The Graphical Plan Editor uses a non-modal dialog now on the first drop of a new node instead of a modal dialog. -- Graphical Plan Tracing Plan Tracing has had some changes to text on the GUI. The prefix before the top combo box no longer mentions plan. Within the combo box, it will prefix plans with "Plan:". The agent execution controller just mentions "Tracing On" rather than "Plan Tracing On". The plan tracer has additional check boxes and panels for Applicable Plans, and Failed Plans, and will trace events associated with a task. Use event name instead of plan name in tracing configuration files. -- Import <Entity> (in browser contextual menu) Importing of external entities has been improved. Any entities referred to from the imported item are also imported. If you attempt to import something whose package and name match an entity that is already present, you are now asked whether you are attempting to reload the entity or if you would rather rename the new one. The file chooser dialog that appears when "Import ..." has been improved. Previously it was necessary to click on a project, then select a component from within the project in the accessory panel and then click the "Import" button. You can now simply double-click on the component in the accessory panel to select it. The "Mark as External" flag is displayed in red when selected to make it stand out better. -- Reload <Entity> (in browser contextual menu) Reloading a component now uses the customised project file chooser dialog rather than a standard file chooser when the original save file can't be loaded for some reason. The "Mark as External" checkbox is no longer displayed for the reload operation since it does not apply in this case. A number of problems with reloading have been addressed. -- Locate Missing Component (in contextual menu on empty or broken reference) The context menu on a reference in the browser (such as the "handles" node for a plan) will have an extra menu item labelled "Locate Missing Component" when the referenced entity is not found or it is simply not set yet. This can be used to relocate the missing entity. The operation has been improved to notice if the save file for the reference is actually there after all (or a backup file exists) and the option is given to use it. Otherwise the previous behaviour takes over. -- Edit as JACK File Fixed problem where any changes made were ignored after an entity was renamed. The JACK files generated by "Edit as JACK file" are shared with (in the same location as) JACK files generated by the JDE for compiling. If JACK files were generated from the command line (java aos.main.Jack -J, for example) while the JDE was running, the "Edit as JACK Files" could be overwritten with old data which was then loaded back into the JDE thus losing any changes that had just been made. This is no longer possible since the JDE can now tell the difference between "Edit as JACK Files" and generated JACK files for compiling. The parsing of JACK files has been improved. Any unforeseen problems with the parsing are trapped now and don't cause any further problems. The user is simply informed that the file is impossible to parse in its current state and is given the opportunity to fix it. Now handles wildcard imports, e.g. "import java.util.*"; Sometimes methods created for graphical plan tracing ended up included twice in the generated text. This should no longer occur. -- External Editor There were some issues with the automatic detection of external editors that detach themselves from the parent process and thus appear to exit immediately. The JDE detects the quick exit and pops up a dialog requesting advice. Previously, if the user made the wrong choice and said that the editor had detached itself when it didn't and also didn't have the preference set to automatically load changes whenever the file was written, then no changes were ever loaded since the JDE couldn't determine when the editor had really exited. This has been addressed in a number of ways: - The time required for an abnormally early exit has been reduced. - The dialog has been improved to reduce misinterpretation. - If the user says that the editor detaches itself, then the JDE will never wait for the editor process to exit before loading the changes; they will be loaded automatically as soon as the JDE detects that the file has been written. -- Compiler Utility The title bar now includes the project name. The "Preferences" tab has been renamed to "Options" to avoid confusion with the application's preferences (available under the [Tools] menu or the application menu on a Mac). The "Generate G-Code" tab has been renamed to "Convert Non-JDE JACK" to make it clear what it is for. It is only useful for converting existing JACK code not currently in a JDE project into its own JDE project. Some of the labels have been changed to be a bit more informative. The "Compile Application" and "Run Application" tabs now have a new "Save Settings" button which will save any options (like "Java Args", for example) so that they automatically appear next time you start the JDE on the same project. The settings are saved on a per-user basis, not in the project file. In the "Run Application" tab, selecting the "Trace Graphical Plans" checkbox and pressing the "Select or Create" button (to select or create a plan/event tracing file) is a bit more informative about what it is doing. A confirmation dialog is shown before creating, overwriting or using the tracing configuration file selected. -- Design Diagram Tracing This feature is accessible from the "Trace" menu. The basic usage is that you select one or more design diagrams to be traced. Then when you connect the JDE to a running JACK application it will notify the JDE when transitions (that map to links in the diagram) occur and they will be highlighted. A configuration GUI is provided to choose the designs to be traced and a simple stop/run/step GUI appears when connected to a running JACK application. In addition a new window appears in the JDE showing all agents within the connected portal. Note: If the "Trace" menu does not appear in the menu bar, you will need to run the JDE with the "-dt" option. I.e. java aos.main.Jack -dt <project-file> The JACK agent application you wish to trace must be started with an additional Java argument to enable it to be traced: -Djack.tracing.enabled=true If the application does not normally do any interprocess communications and does not create an explicit portal, then you may wish to start the system with appropriate DCI arguments. For example, to create a portal called Server at the given address: -dci.new:Server=localhost:9999 Note: JACK will not understand any "-dci" arguments unless the application calls aos.jack.Kernel.init(String[] args) in the main() method. See the JACK Agent Manual for details. Alternatively, you may change the parameters for the default portal that is created automatically by setting any of the following properties: -Djack.portal.name=<name> -Djack.portal.host=<host> -Djack.portal.port=<port> These normally default to "%portal", "localhost" and "0" (which means use any available port number). You will then connect to this portal name or address using one of the 'Connect' options in the Trace menu. Once your application is running, you start the JDE. The Trace menu has 5 choices: + Connect To Nameserver... Use this to connect to a name server you have set up with JACK's DCI capabilities. + Connect To Portal... Use this to connect to a portal using the portal name or address. Once connected, the portals window will be displayed. If you have already connected to a name server, you would normally connect by specifying a portal name only. Otherwise you would use an explicit address. + Configure Design Tracing This allows you to choose which designs in a project will be traced. + Design Tracing Controller This will pop up the Design Tracing Controller window which can be used to start, stop and step execution within a particular portal. The window will automatically be displayed the first time something happens that is being traced. + Ping Agent... Use this to check if the remote portal knows about the given agent. You can set the number of retries and the delay in seconds between ping attempts. Once connected to a portal, a window within the JDE will appear showing the portal in a tree browser view. The portal can be expanded to reveal the agents within the portal. After setting up the diagrams to be traced and connecting to an application's portal, running the connected JACK application will notify the JDE whenever anything interesting happens in the diagrams that are being traced. The traced diagrams will appear, highlighting the transitions that just occurred. [The rest of this file contains change notes for earlier releases] JACK INTELLIGENT AGENTS™ v4.6f (update) Compiler Changes: Fixed compiler issue causing spurious syntax error when a String identical to a variable name appeared in close parsing proximity. In teams mode, all Agent types (if present) *must* extend Team rather than Agent. This was previously allowed but may have caused unexpected behaviour. If you get the compilation error "Must derive from aos.team.Team or from a subclass of it" then you are compiling using the Teams map when you shouldn't be or you need to change the baseclass of your Agent types to Team. If you are compiling using the JDE, check that you are not in Teams mode by mistake (check under the View menu). JACOB Changes: When writing JACOB objects (ASCII or XML), object IDs (tags) are now only written if the particular object is actually referred to. Previously all JACOB objects were written with a numeric ID. Some string fields were being initialised to the string "null" instead of null. JDE Changes: Added "java aos.main.Jack -UJ <project-file>" option similar to "-J" for generating the JACK code in batch mode but it only regenerates files that are out of date. Provided a way to stop JACK compilation from within JDE. "Compile" and "Generate" buttons change to a "Stop" button while the process is active. Also added a "Stop" button to the Output/Errors tab for convenience. An item has been added to the File menu to remove any generated JACK files. (It actually renames them to *.bak files.) You can now drag text-line items (such as imports) onto other text-lines to copy the value. Note, You can't currently do this within the same folder since dragging within the same folder will re-order the items within the folder. Importing an external component (via a project file) will now attempt to automatically import any other component it references. They will also be marked as external and will be grouped in their own folder based on the package they came from. This will usually not work correctly if a component is imported by loading its gcode directly rather than by going through the project file that the component(s) belong to. The (original) contents of any external components are now cached in a folder called "ext-cache" instead of being saved in the project file. This should further help avoid contention for the project file when multiple users are working on the same project. An imported (but not external) component from a different project is now marked as changed so it will be saved within the current project. This effectively makes a copy of the component. Importing a missing component (not as external) from the same project is detected and is not treated as a copy (see previous entry). Fixed problem with Named Data which used an external component as the underlying type. Also some general improvements in the handling of external components. Using an external editor to edit an "Other File" now edits the actual file instead of a temporary file. Editing using "Edit as JACK File" edits the actual file that the JACK compiler will see. "Edit as JACK File" now correctly updates the browser structure when a "#handles" statement or a "#applicable for" statement is removed. "Edit as JACK File" works better for plans that do not yet have an event to handle. "Edit as JACK File" works better for team plans. "Edit as JACK File" no longer discards all text reasoning methods if there are any graphical reasoning methods present. Make sure Agent types are being shown if some exist even if the option to show them is not set (while in Teams mode). Graphical Team Plans can now have labelled parallel task nodes. The default establish() method generated for a TeamPlan now calls defaultEstablish(). An empty establish() method causes the TeamPlan to misbehave. Added CTRL-SHIFT-S keyboard shortcut that will (re)save all loaded components whether or not they are marked as changed. (CTRL-S saves any changes as before.) Allow the user the option to create all required folders when asked about creating a save sub-folder which does not exist yet. Previously a question was asked for every non-existent folder. Fixed problem in "atm" example from within JDE -> Help -> Create From Example Misc. Changes: When Portal creation fails, the exception is now propagated instead of being caught and ignored. JACK 4.6 - EXTERNAL EDITOR SUPPORT IMPROVED The JDE allows you to use your own choice of text editor for viewing and/or modifying textual components such as code blocks and documentation. There are a number of preferences that can be set under the "Text Editor" tab of the Preferences dialog. Changes made by an external editor will be loaded in when the editor exits or optionally, whenever the text is saved by the external editor. The small control panel that was previously associated with each external editing session is now optional. The external editing works best when the JDE can keep track of the external editor process. Some editors detach themselves and run in the background. They may seem to exit immediately (which the JDE will detect) or they may seem to never exit (which won't be detected). On Windows, using Notepad or Wordpad as the external editor can have this effect. In this case it is recommended that you edit the preferences from the Edit menu, select the "Text Editor" tab and set the "Load changes as soon as the file is saved..." preference; also the "The external editor detaches..." preference; and also, the "Popup a control window..." preference. Some editors have an option to run in the foreground (e.g. gvim -f) or background. If possible, use an editor that runs in the foreground (i.e. non-detaching). NOTE: External editors will run in their own window and will not belong to the JDE desktop. External editors will often seem to disappear because most actions will bring the quite large JDE desktop to the front of the screen and hide any external editors. - TEXT EDITING OF ENTIRE JACK COMPONENTS This now works for JACK Plan types and JACK Team Plan types. Right clicking on a JACK component in the browser gives you the option of "Edit as JACK File". This will present the component in textual form and allow editing using the internal JDE editor or an external editor. When the editing is finished the text is parsed and broken up into its individual elements and the component in the browser is updated accordingly. After editing a component as text, some elements may be re-ordered, re-named, re-structured or even removed if they are not required. Some textual elements, notably those resulting from graphical reasoning methods, can be edited but the changes will be ignored. These text elements have clear comments stating this. NOTE: do not make changes via the browser while editing something as a JACK File or you will lose those changes when the JACK file is processed back into the browser. - NAMED TYPES NOW SAVED SEPARATELY Separate save files are created for each named type now. Named Data are stored in a file with a ".gnd" extension and Named Roles are stored in files with a ".gnr" extension. This should make it easier for multiple users to work on the same project since they don't have to contend for the project file (*.prj) where the named types were previously stored. Note: a warning will be given and the project will be marked as changed when an old project file containing named types is loaded into the JDE. This is so the named types will be properly saved in the new format. - GRAPHICAL TEAM PLAN EDITING Right click on a newly created TeamPlan and choose "Edit Graphically" to edit that team plan in the graphical team plan editor. This editor generally behaves like the graphical plan editor. - NEW TEAM PLAN NODES There are new nodes in the Plan Node Palette that can be dropped on to graphical team plan graph's: * Begin Parallel This node represents the start of an @parallel statement. It should always have a matching End Parallel node at some point in its flow. * End Parallel This node represents the end of an @parallel statement. It should always have a matching Begin Parallel node. * Parallel Task Each task in an @parallel is represented as a collection of nodes, optionally beginning with a Parallel Task node. This node contains any exception handling code for that task. Each node in an @parallel statement belongs to exactly one task. * Team Achieve The @team_achieve statements are represented as a single node in the graph. - GRAPHICAL REASONING METHODS A blank body, pass and fail graphical reasoning method is created by default when graphically editing a team plan. - EXCEPTION HANDLING Each graph in a plan has the ability to set exception handler code to be used when executing that graph. - GRAPHICAL TEAM PLAN CODE GENERATION This release includes the ability to generate team plan code from graphical team plans. - DESIGN TOOL DESCRIPTIVE MODE Designs can now show their nodes in descriptive mode rather than display their actual names. - NEW PREFERENCES It is possible to set a preference to always show designs in descriptive mode by default. It is possible to set the prefix and suffix of the temporary file name used when editing using an external editor. You can toggle whether changes from an external editor are loaded as soon as the changes are written out, or instead, only when the external editor is closed (exits). An external editor can be declared to "detach itself" in which case the JDE will not pay attention if the external editor exits. If this option is not set when it should be, the JDE will warn you when the first external editor is created. If the option is set for an editor that does not actually detach itself it, the JDE will unnecessarily behave as if it is detached and not notice the process exiting. Each external text editor may have its own small control window in the JDE. Previously this was not optional. A numeric threshold can be set to control whether changes are confirmed when editing a component in textual form using the "Edit as JACK File" selection. The default of 0.5 is fairly conservative. A setting of 4.0 or 5.0 will tend to suppress the confirmation dialogs completely and always accept the changes directly. The compiler utility window contains a new preference to clean up before compiling. This may be useful if the JACK compiler confuses automatically generated Java files for original source code thus causing "multiple definition" errors. The "Discard Errors" and "Discard Output" preferences have been removed from the compiler utility. - OTHER BUG FIXES In "Other Files", it is now possible to close an editor window without saving the file. When editing a file ctrl-s/command-s no longer brings up a find and replace menu. The remainder of this document contains the release notes for JACK 4.0. DOCUMENTATION ------------- The documentation can be found in the "doc" folder where JACK was installed. Open "jackdocs.html" in your web browser to get easy access to all the documentation including this file (README.TXT) and CONVERT.TXT for information about converting old (pre 3.5) JACK code to remove deprecated language features. IMPORTANT NOTES --------------- JDK 1.3 (or greater) is now required (for the graphical components; JDK 1.1 is still sufficient for the JACK compiler). Class files generated by different versions of JACK are not compatible. It is recommended that all old class files be removed before compiling with a new version of JACK. The JACK Development Environment (JDE) requires a sizeable amount of memory to run well. If you find you have performance problems we recommend that you give Java at least 85MB of memory to use; possibly more. Invoke it as: java -Xmx85m aos.main.Jack (or simply run it from the Start -> Agent_Software Menu on Windows which will allocate 85MB automatically. The amount can be changed by editing the *.lax files). Please report any problems you encounter to jack-support@aosgrp.com and mention the release of JACK you are using and any steps required to duplicate the problem. NEW JACK FEATURES FROM JACK 3.5 - NEW COMPILER OPTIONS The "-map=team" and "-map=teamsim" options are a simple way to specify that the compiler should use the alternate syntax for either JACK Teams or JACK Sim (simulation module) respectively. - JACK COMPILER CHANGES The JACK compiler has significant changes to improve basic compatibility with the Java language. In reasoning methods, "switch" statements now work better. JACK's type resolution has been improved: if your JACK component "implements" an interface containing constants, the constants will now be accessible without qualification (as Java does). The assert and retract methods for Beliefsets are no longer available by default. To re-enable them, use "-Djac.emitassert=true" when compiling. Instead of assert/retract, use the add/remove methods to avoid this issue. - JACK TEAMS MODE The JACK compiler has four new types for teams programming. Team, Role, TeamPlan, and TeamData - DCI ENHANCEMENTS The built in agent communications infrastructure is now more robust. If processes exit for any reason they can be restarted and they will be able to resume communications where they left off. Messages sent while the process was gone will be lost of course but normal operation can be resumed mostly automatically. Previous versions of JACK had trouble with the reconnection process. Processes now automatically keep their name server(s) informed of new connections that they make. When a process makes an initial connection to a nameserver, the nameserver will update its list of known addresses. This can be used to implement a robust network containing two or more nameservers so that no information is lost if one nameserver goes down and subsequently comes up again. Some new methods have been added for checking if a particular agent is running and available on the DCI network. These methods are in the aos.jack.jak.core.Dci class. public static boolean pingOk(String agent_name); public static int ping(String agent_name); This times-out after 15 seconds. public static boolean multiPingOk(String agent_name, int timeout_msecs, int period_msecs); public static int multiPing(String agent_name, int timeout_msecs, int period_msecs); Possible return values from methods returning 'int' are: Dci.PING_NOT_READY - no portal in current process Dci.PING_UNKNOWN_PORTAL - given portal not connected Dci.PING_UNKNOWN_NAME - given name not known at portal Dci.PING_OK - given name at portal responded public static boolean multiPingOk(String agent_name); JACK DEVELOPMENT ENVIRONMENT (JDE) ---------------------------------- - AGENT MODEL/DATA MODEL SPLIT The project browser has been restructured. The top level components have been split into two groups depending on whether they are related to the agent modelling aspects of the project or the data modelling aspects. - NAMED DATA A new basic type has been added called Named Data. A Named Data is simply a named version of one of the basic belief data types; Beliefset, View, External Class or Java File. EACH BASIC BELIEF DATA TYPE CAN NO LONGER BE DROPPED DIRECTLY ONTO OTHER COMPONENTS such as Agents and Capabilities -- they must now be named by creating a new Named Data first and these can then be dropped instead of the basic type. This allows you to differentiate between different uses of the same belief data type and is particularly useful when used with the Design Tool. Note: old projects will be converted to the new format automatically. - NAMED ROLES This is a new component type similar to Named Data. It provides a specifically named Role type and is used when specifying a "requires" relationship. The normal Role type is still available for other uses such as specifying a "performs" relationship. - NEW VIEW MENU A "View" menu has been added. This allows you to quickly alter some of the characteristics of the project browser. It allows you to view (or hide): + Full Package Path + Documentation Nodes + Teams Mode Switching Teams mode on or off has the side-effect of providing different options to the JACK compiler as well as showing/hiding the team specific components. - DESIGN TOOL A new top level component called "Design View" has been introduced. Building a design provides an alternative way of building an application as well as providing an effective way to visualise it. Component types can be dragged and dropped onto a design view, links can be made and all changes are reflected in the browser project window. Similarly, changes made in the browser project window will be reflected in any design which includes the changes components. The design tool has a comprehensive printing facility. See the JDE Design Tool User Guide for details. - LOAD/IMPORT-EXTERNAL FUNCTIONALITY MERGED The file chooser for importing existing JDE files (gcode) has been enhanced so that it is possible to choose whether to load an existing component as "external" or not. You also have the choice of loading the component as a "stub". I.e. the component will be created with the same name and package but will be empty. When using the chooser to load existing JDE files (gcode) via a project file, multiple components can be selected at once. - COPY COMPONENT A new "Copy" option has been added to the component menus. - PLAN EDITOR/COMPILER A graphical plan editor and compiler has been added to the JDE. As an alternative to writing plans in textual form, it can be done in a simple drag and drop way; drawing nodes and links in a similar way to the design tool. Choosing "Update JACK Files" from the "File" menu will generate JACK code for any graphical plans. Errors and warnings from the Graphical Plan Code Generator will appear in the new "Error Log" window which is available from the "Window" menu. See the JDE Graphical Plan User Guide for details. - GRAPHICAL PLAN TRACING TOOL It is now possible to graphically trace plans developed with the JDE. You must first generate your JACK files from the JDE with the the "Generate Traceable Plans" option selected in the Preferences Panel, under the "Graphical Plans" tab. Once generated, you should compile your application as usual. To run your application with tracing on, you can either use the JDE's Compiler Utility, or run your application from the command line. There are a number of Java properties that need to initialise the graphical plan tracing. See the JDE Graphical Plan Tracer Technical Brief for all the details. - NEW PREFERENCES A number of new preferences have been added. These include fonts for the project window; whether or not to start in teams mode; whether to remove restrictions on the top level folder structure. Preferences for the new Design Tool, Plan Editor etc. have also been added. - COMPILER UTILITY The Run tab now allows you to specify a tracing configuration file. After pressing "Stop" from the Run tab, a misleading popup message is no longer produced. - KNOWN PROBLEMS * There is sometimes a problem when generating a project file from existing JACK source code for use with the Jack Development Environment (JDE). If the application normally compiles correctly but fails when using the -E option to generate a project file, you should clean out the old compilation files and try again. Use the "Cleanup" button within the JDE Compiler Utility or type "java aos.main.JackBuild -c" when using the command line interface. * A similar problem to that described above may also occasionally occur when compiling a JACK application in the normal way. Although not usually necessary, if you get obscure errors from the JACK compiler, it is sometimes worth trying to clean out old compilation files before trying again. Use the "Cleanup" button within the JDE Compiler Utility or type "java aos.main.JackBuild -c" when using the command line interface. * Under Linux using Sun's JDK 1.3 we have heard a report of occasional problems with the Java HotSpot compiler. If affected you should try the "-classic" option when running Java. * The real-time clock on some Linux kernels has been reported to behave erratically under certain obscure circumstances. Although rare, this could cause the JACK task scheduler to misbehave. If this should occur, JACK will detect the situation, attempt to compensate and report that there may be a problem. This does not seem to occur on the Solaris, Mac OS or Windows platforms. * Under Mac OS X, the internal text editors may behave badly - in particular when scrolling text. If you find you have problems, try using an alternative external editor (for example, use "open -a TextEdit" in the Text Editor tab of the Preferences). Please contact jack-support@aosgrp.com to report problems or jack-sales@aosgrp.com for general information. ------------------------------------------ Agent Oriented Software Pty. Ltd. P.O. Box 639 Carlton South, Victoria 3053, Australia phone: +61 3 93495055, fax: +61 3 93495088 email: jack-support@aosgrp.com http://www.aosgrp.com ------------------------------------------