See the main page for a Cress overview
The current version of Chive is 2.0, dated 11th October 2012
Chive (Cress Home-grown Interactive Visual Editor) is a dedicated graphical editor designed to create service diagrams for use by Cress (Chisel Representation Employing Systematic Specification). See the Cress page for an overview of Cress.
Chive is based on the following open-source packages:
Chive consists of a single JAR (Java Archive) file. To run it requires a JRE (Java Runtime environment). Install it anywhere convenient - and possibly also the chive script and the chive.ico icon.
The complete source code is provided in case you wish to rebuild or edit Chive. (Unfortunately the JavaDoc for Chive is rather incomplete.) The modified source for EpsGraphics will be made available on request. The Chive folder can be imported as an Eclipse project. An ant build file is also included. Chive needs to be built against JGraph and EpsGraphics, so JAR files for these are included in the lib folder. Chive may build and run against later versions of JGraph, though this is not guaranteed.
Chive can be started as follows:
java -classpath chive.jar uk.ac.stir.cs.chive.ChiveEditor
One file name can optionally be given following this. Diagrams are stored in XML format, and have the suffix .chx (Chive XML). This suffix can optionally be omitted when using the tool. As an example of starting the tool to edit the diagram diagram.chx, do:
java ... "C:/Documents and Settings/me/diagram"
If the startup file does not exist, the editor will begin with an empty diagram as a quick way of creating a new one.
Chive can also save diagrams as EPS (Encapsulated PostScript), but does not read this format. Such files are named diagram.eps. Text in diagrams is exported as curves. Directly exporting text is unfortunately not possible because the Java libraries use drawGlyphVector rather than drawString. As a result, the EPS files are very large. However, on the plus side the EPS files are platform-independent and scalable.
The chive Perl script provided can be used to automate startup. Place it and chive.jar in the same folder on your PATH.
On Windows XP, just double-click chive.jar in Windows Explorer. It is also possible to arrange that a Chive diagram is opened when clicking on its file name in Windows Explorer. In Windows Explorer, choose Tools/Folder Options.../FileTypes and click New. Enter .CHX as the file extension. Select this and click Advanced. Enter Chive XML Diagram in the text box. Click Change Icon and select chive.ico wherever you installed it. Click New, enter open and click OK. Now click Edit and enter something like the following (all one line) for the application to open the file:
"C:\Program Files\Java\jre\bin\javaw.exe" -classpath C:\usr\local\bin\chive.jar uk.ac.stir.cs.chive.ChiveEditor "%1"
using the actual paths where you installed Java and Chive.
On Windows Vista and Windows 7, there is no equivalent to this procedure. A utility such as Default Programs Editor can be used. In Windows Explorer, initially set a Chive file to open with Java. Then use Default Programs Editor, select File Type Settings then Context Menu then .CHX. Choose Open and edit the call as above. The Chive icon can also be set at the same time. Again withDefault Programs Editor, choose Icon then .CHX and use the Chive icon.
The user interface should be quite familiar, and so will not be explained at length. The key commands from the menu are repeated on the toolbar. Selected commands are also available from a pop-up menu obtained by right-clicking the mouse. Most commands have a keyboard shortcut (see the menu for these).
An example of Chive in use is shown below:
Points of particular note are as follows.
Being written in Java, Chive should run on many platforms. It has been mainly tested on Windows XP, with some testing on Solaris 8 and Linux FC 4. The GUI varies a bit according to the platform, and factors like the fonts available will vary. Some platforms may limit the page layout, e.g. the permitted margin sizes.
Some example diagrams are provided in the samples folder. These have been drawn with 5mm margins for A4 paper (which may be too large for your printer) and with the Arial Narrow font. If this font is not available on your system, you could systematically change Arial+Narrow in the *.chx files to something else, e.g. Nimbus+Sans+L+Condensed. (Note that all such text is URL-encoded, so a space is '+'.) The Cress bin directory contains the chive_font script for automating font changes.
Use the preferences menu to adjust fonts, colours, page layout, etc. Note that font changes apply only to new edits; existing text remains unchanged. A few preferences (notably the number of undos) apply when the editor is restarted. In general, it is best to set preferences initially and stick to them.
The editor remembers the name of the last file opened and the last file saved. This eases navigation to the correct folder. When a file is saved, the previous version is backed up under a name like diagram~.chx or diagram~.eps. When a file is saved, the grid setting, the zoom setting, and the scrollbar positions are also saved with the diagram.
Use Save to save the current diagram without a dialogue, or Save As to choose a new file name. Also use Save As to save a file in EPS format. The suffix .chx or .eps is added as appropriate if not supplied.
Chive handles just one diagram per window. However, it can be started more than once if there are several diagrams to edit. Copy-and-paste can be performed between different Chive windows. Error messages are sent to 'standard error' (a console window or Java console) and to a popup window. The position and size of the window are remembered when Chive is closed. It is possible to zoom in/out of the current diagram to an arbitrary extent.
The New command also opens a new window; the extra windows are numbered 2, 3, etc. Closing the main window closes all windows. The windows can be edited independently. However, interference will occur if you try to change preferences in different windows or to validate against the same root diagram in different windows.
You can print all pages of a diagram or just a range. As with any Java printing, the spooled printer files may be very large.
If you have Adobe Acrobat or similar, you can obtain PDF directly through printing (though this is created from a bitmap). PDF can also be obtained by saving as EPS and then using a standard utility to convert it. Failing this, zoom in and capture the window (Alt-Print Screen on Windows) for conversion to some graphics format.
A grid can be turned on. The grid size is adjustable through preferences. It is possible to turn snap-to-grid on or off. If a symbol is resized while snap-to-grid is on, its position and size of the symbol are snapped to the grid points. While the position or size of a symbol is being adjusted, its centre point and size are shown in the status bar. Objects can be 'nudged' a small amount (determined through preferences) by using arrow keys with Control pressed. (The arrow keys on their own just move the viewpoint.)
Initially a diagram has one page, but it is possible to append a further page (below the current page). The light grey lines mark the boundary of pages; symbols drawn outside this will not be printed. The last page can be removed if required. Anything drawn on this is not lost - it just becomes invisible and will not be printed. Zoom out to see the hidden symbols and copy them to other pages.
A symbol can be placed behind or in front of existing symbols. Draw a rectangle around a group of symbols to select them, or Shift left-click to extend the selection. The symbols can be grouped (or later ungrouped). Unlike some graphical editors, Chive allows individual symbols in a group to be selected and adjusted.
A number of symbols can be aligned horizontally or vertically by selecting them and then choosing one of the Align options.
Changes can be undone or redone, up to a limit determined in the preferences. Note that undo/redo does not operate on text that is being edited - only on modifications to symbols and arcs.
Hold down Shift during dragging to constrain the result. When repositioning, this forces a strictly horizontal or vertical move. When resizing, this ensures the same horizontal and vertical dimensions (e.g. a circle or square).
Hold down Control during dragging to make a copy. When repositioning, this copies the selected symbols.
It is probably more convenient to insert these use the right mouse menu, since they will then be inserted at this point in the diagram. Since a connector has no border, it is wise to immediately add text to it since it would otherwise be invisible!
By default, symbols have shadows. This effect can be turned off by setting the shadow size (in preferences) to zero.
An arc between two symbols is drawn by first hovering the mouse near the centre of the source symbol; the cursor will change to a hand. Then press the left mouse button and drag to the centre of the destination symbol. When at this point, the destination will be highlighted by a light rectangle. Release the left mouse button to finish the arc. Arcs are normally connected to symbols. When a symbol is dragged to a new position, its attached arcs follow it.
It is possible to make a curved arc by adding 'bends' to it. Hold down Shift and left-click on the arc; a small control point will be shown. This can be dragged to create a curved arc. Shift and left-click on a control point to remove it.
An arc can be detached from a symbol by dragging its endpoint. If one of the symbols attached to an arc is deleted, its endpoint becomes detached. A detached endpoint can be re-attached by dragging it over a symbol.
If necessary, a loop from a symbol to itself can be created by drawing an arc to some other destination. Add at least two bends to the arc, then drag the endpoint to the original symbol as destination.
Double click on a symbol or on arc to add or edit a label. (Do not double click near the centre of a symbol or it will be assumed that you wish to add an arc.) Portions of the text can be made bold or italics. Remove a label by setting its text to empty.
The label on a straight arc is centred on it. If the arc is made curved, its label may end up in an unsuitable position. Drag the label with the left mouse button to reposition it.
Chive has an interface to call Cress tools to check diagrams. The output of these tools appears in a pop-up panel, and also in the window status bar as the tools run.
Cress requires a particular file structure. Suppose you are creating the service BOOKING for the IVR domain. The Cress root folder must contain the folder ivr for the domain. Inside this must be the folder booking for the service. The BOOKING diagram must be stored as booking.chx in the service folder. (The service folder stores related files as well, such as booking.mustard for Mustard scenarios and booking.clove for clove properties.) Schematically this looks like:
cress
ivr
booking
booking.chx
booking.clove
booking.mustard
...
...
Preferences must be used to access the Cress environment. The Tool Shell is typically Perl. This needs to be defined (e.g. as 'perl -S', though the full path to Perl may be needed). If the shell command is prefixed with '@', this indicates that the diagram should be uploaded to a remote server and the command executed there (see Remote Upload below).
The application domain and target language also need to be defined; not all combinations are supported by Cress. Other tool options may be defined if required (e.g. -e 0 for diagnostic output from Check, or -m to define merge partners).
Cress operations would normally be used in the following order: Check (optional, for pre-deployment check), Deploy, Validate (optional, for rigorous development), Verify (optional, for rigorous development), Invoke (optional, for pragmatic development), Undeploy (if development work is to be removed).
This checks the syntax and static semantics of the current diagram, for the selected vocabulary (and target language in some cases).
When used with a configuration diagram, this realises the services/features in this diagram and deploys them as appropriate. When used with a root diagram, this overrides the diagrams named for deployment in the configuration diagram.
When creating Lotos, SDL or VoiceXML, the realisation is a specification to be processed separately. When creating BPEL, the realisation is an implementation deployed to ActiveBPEL and/or Globus on the local host. For BPEL deployment to a remote system, the server host (and username/password if secure) are required. When creating CPL, the realisation is an implementation deployed to a SIP server. For CPL, the server host (and username/password) must be specified by setting the Chive tool option '-k user:password@host'. If the implementation server is not running, then Chive may hang up during deployment.
This checks the dynamic semantics of a diagram against the use-case scenarios defined by Mustard. The progress of validation is shown in the status bar. Note that the specification used is the one defined by the configuration diagram. If the current diagram is not included in the configuration, no scenarios will be run.
This checks the dynamic semantics of a diagram against properties defined by Clove. The progress of validation is shown in the status bar. Note that the specification used is the one defined by the configuration diagram. If the current diagram is not included in the configuration, no properties will be checked.
This invokes the service using the input values that are prompted for; these are saved with the diagram for future use. The format of inputs is dictated by Cress, not Chive, but in general will be a space-separated list. If an input value requires spaces, these may be given in double quotes.
This removes the service and anything that depends on it. In general, this removes the diagram directory by moving it to a temporary location (where it may disappear at any time). For BPEL, the corresponding process and its partners are undeployed from the BPEL engine.
Chive can upload diagrams to a remote server for analysis and deployment. This is triggered by prefixing the Tool Shell in Preferences with '@' (e.g. '@perl -S'). When a remote tool is run on a diagram, Chive asks for Server Preferences. At the least, the Server Path must be defined as the server name followed by an optional path (e.g. 'dames.cs.stir.ac.uk/cress' or 'localhost:8080/chive/upload').
If the server is secure, specify a username (and password) for the remote server. It is then assumed that the server uses HTTPS. The password is stored in memory while Chive is running. Set the check box if the password should be stored when Chive exits. Note that this is potentially insecure since the Chive properties file would then contain the password in clear.
It is possible to upload and Check a diagram in isolation. However, for other tool commands a configuration diagram must have been previously uploaded to the server (using the Check command).
The uploading process zips up the diagram. If the diagram shares the same base name as its parent directory (e.g 'lender.chx' in 'lender'), everything in that directory (and its sub-directories) is uploaded. However for efficiency, only files that have changed since the previous upload/download are included. This is done by maintaining a file diagram.upload, named after the Chive file. The last modification time of this file determines which newer files need to be uploaded. If it is necessary to upload all files again, delete diagram.upload first. (This is done automatically when choosing the Undeploy command.)
The zip file is sent to the server, where it is unzipped into a top-level directory named after the secure username (or 'anon' if not secure). The diagram (and any associated files) are stored in a sub-directory named after the diagram (e.g. 'lender.chx' is stored in 'lender'). The uploaded files remain on the remote server, and will be overwritten by any subsequent uploads of a diagram.
The Cress tool that runs on the remote server may create files that need to be downloaded to the client. These are zipped up and sent back to Chive, where they are unpacked in the original diagram directory. The Cress tool will indicate in its results which files have been downloaded. Much as for upload, a file diagram.download is maintained on the server to avoid unnecessarily downloading files back to the client.
Uploading requires code on the server to receive files from Chive. As an example, jsp/upload.jsp is provided for adaptation.
This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation - either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
You may re-distribute this software provided you preserve this Chive description. Bug reports should be sent to Ken Turner, who would also appreciate receiving any corrections and comments.
Jamie Boyd undertook the early development of Chive under the supervision of Ken Turner. Chive relies on the JGraph package. Chive was also inspired by, and partly based on, JGraphPad. EPS export is thanks to EpsGraphics.
Version 1.0: Internal release, Jamie Boyd, 15th September 2004
Version 1.1: First public release, Ken Turner, 1st August 2005
Version 1.2: Minor bug fixes, Ken Turner, 8th August 2005:
Version 1.3: Ken Turner, 9th May 2006:
Version 1.4: Ken Turner, 1st September 2006:
Version 1.5: Ken Turner, 27th August 2007:
Version 1.6: Ken Turner, 26th September 2007:
Version 1.7: Ken Turner (with contributions from Koon Leai Larry Tan), 15th April 2009:
Version 1.8: Ken Turner, 27th July 2010:
Version 1.9: Ken Turner, 3rd March 2012:
Version 2.0: Ken Turner, 11th October 2012: