Routed Systems Designer Java API interface. =========================================== Example Java code - JGTestFrame.java ==================================== ++++++++++++++++++++++++++++++++++++++++++++ CONTENTS 1. Features in the demo file 2. Compiling and running the demo file 3. Further modifications ++++++++++++++++++++++++++++++++++++++++++++ 1. Features in the demo file Included with the RSD Java API is an example Java source file, JGTestFrame.java. It demonstrates several features of the Java API for communication with RSD: a. Obtain the current design object (as a rsdesigner.design.Design object) The design object is obtained at line 266: Design design = Design.getCurrentDesign (); Notice that the obtaining of the current design object and the actions performed on that object are all performed within a synchronized() section, started at line 257: synchronized (Design.getSynchronizeObject ()) The object that is synchronized on is used as a monitor by the RSD system, so that when in that monitor RSD will not be able to respond to UI actions (e.g. closing the design). Obviously if too much time is spent in the monitor by a Java method RSD will seem to have 'locked up'. b. Query the design object for Components in the design (i.e. Groups, Blocks and Fibres) The query is perfomed by calling Design.select() (line 319). The demo file includes an example Pre-filter, condition list, sort specification list and class list (selectable using the checkboxes in the Swing dialog). Once the select statement has completed an Iterator is returned that contains the Artifacts that match the criteria, in the order specified by the sort specification. c. Find children, parents and shapes of Components. Once the select() has completed the section from line 349 onwards does some querying of each component to print out what parents, children and shapes they have. If a component has ports then the connected ports are also returned. d. Obtain values of properties on Components. Line 340 obtains the name, class, type and sheets properties from each component, ready to be displayed in a Table object in the demo dialog. e. Use of Swing to display custom dialog boxes The JGTestFrame object is a subclass of a Swing JFrame. When the static method openTestFrame() is called a Swing dialog is shown that has a JTable (to display the results of the select() query), a 'refresh list' button and several checkboxes. Clicking the 'refresh list' button will cause the select() query to be performed (with parameters set by the checkboxes' state and the results of that query to be shown in two areas - the JTable and printed on the console window. f. Use of multi-threading to communicate with RSD At line 32 there is a definition of a class RefreshThread that can be used to run in the background and periodically call the 'refresh list' action. The creation of thread is currently commented out, but can be re-enabled by removing the comments at line 223 and 224: refreshThread = new RefreshThread (this, "RefreshThread");. refreshThread.start (); On removing the comments and recompiling the 'refresh list' method will be called every 30 seconds. ++++++++++++++++++++++++++++++++++++++++++++ 2. Compiling and running the demo file Compiling --------- In order to compile the demo file it is necessary to have the CLASSPATH set to the location of the Java API. The package files are stored in a directory called 'java' in the installation directory of RSDesigner. Therefore, if the user's installation is at: C:\rsd\i486_nt\rsdesigner then the user would need to set the CLASSPATH to set CLASSPATH C:\rsd\i486_nt\rsdesigner\java Once the CLASSPATH is set up the user will need to create a directory to store the compiled .class files (it could be the same directory as the .java files are in, but that is not recommended). The JGTestFrame.java file is then compiled with the following command: javac -g -d C:\rsd_client_classes JGTestFrame.java where: -d d:\rsd_client_classes informs the compiler of the directory chosen to store the compiled .class files -g is a flag to turn on debugging information Starting RSDesigner with Java enabled ------------------------------------- The user must inform RSDesigner when starting up where to get the custom Java files. This is done by setting the environment variable: CLIENT_CLASSPATH C:\rsd_client_classes Now when RSDesigner starts up it will be able to find the newly-compiled Java classes. In order to debug a compiled Java class the user must set up another environment variable DEBUG_JAVA true will enable a JDPA TCP/IP debugging socket on port 8787 when the Java virtual machine starts up. Running a Java class -------------------- Starting the demo class is achieved by customizing the Java button to call the static method openTestFrame(). Following the instructions in Creating Customizable Java Buttons in the RSDesigner manual: * click utilities>customize UI * choose a java button (e.g. dg_tooltray_user_java_button) * set the Java string to be: JGTestFrame.openTestFrame(hello) * click the ok button Now open a design and then click the newly-modified Java button in the Diagramming tooltray (it is at the bottom left by default). The result should be: Initialising Java Gateway Received hello. Now opening window and then a Swing dialog should appear, titled 'RSDesigner Java Console'. Now click the 'refresh list' button and (assuming there are any Components in the design) the following should be observed: SelectPreFilter.filter Fuse-G (note: Fuse-G is the name of a Component) SelectPostFilter.filter Fuse-G SelectPreFilter.filter Ground-G SelectPostFilter.filter Ground-G ... Found artifact 1 port Simple_Port_no_label has shape rsdesigner.component.BlockShape {refc 70942 type 43} has portshape rsdesigner.component.PortShape {refc 70798 type 43} has portshape rsdesigner.component.PortShape {refc 70510 type 43} has container rsdesigner.component.GroupShape {refc 70622 type 43} has top level container rsdesigner.component.GroupShape {refc 70612 type 43} has diagram type 3 Found artifact variable connector has member 1 at index 1 at varindex 0 has shape rsdesigner.component.GroupShape {refc 69165 type 43} has membershape rsdesigner.component.BlockShape {refc 69259 type 43} at index 1 has container null has top level container null has diagram type 3 ... Found 309 Artifacts Refreshing complete The refc and type information is the internal representation of the object in RSDesigner and not useful to the user, but it is used to show that it has a unique presence in the system. ++++++++++++++++++++++++++++++++++++++++++++ 3. Further modifications This demonstration code has potential to display further information in the table object. Also extra reporting (or less, for that matter) could be built in. Examples are: connection lists (maybe from a particular block/fibre/port), further properties of the selected artifacts could be displayed. The intention of this demonstration code is to show what the read-only Java API can report back to the user. Built-in reporting in RSDesigner will never give all the information that a customer will want, but at least now they can obtain that information and present it in a format specific to them.