Jarnal - Collaboration and Networking

by David K. Levine

Collaboration

Collaboration between different machines is supported. Open a document on one machine and choose Start Server from the Collaborate menu. You may choose which port the server binds to; if you will accept any available port, choose port 0. The port used will be displayed in the status bar. Then from the same or another machines, open a document and choose Connect to Server from the Collaborate menu, or choose a bookmarked server. Enter the name or ip address of the server in the dialog box, you may include a port as in localhost:1189. If you do not specify a port, the default port 1189 will be used. You may connect as many clients as you like. Initially the GUI's of all of the collaborating windows are locked. To make changes, you must request control of the document using the Request Control button; once you have control, you may use the button to Release Control. Only one person at a time may have control. Changes made on the controlling document are reflected in real time on the collaborating documents. If the server has control of the document, client connections are blocked until control is released; when client connections are being requested, the Release Control button on the server turns yellow.

Limitations:

Networking

Jarnal supports retrieving files to and from webservers. Files loaded at startup may be specified as URLs starting with http://. Jarnal will attempt to download the requested file using http, and will save the result locally as a temporary file and open it. Background files, metadata files, template files and .jaj files may all be accessed using http. The use of metadata files (see the startup documentation) is especially recommended for loading over the network, as these are designed to be generated by the server on the fly and provide pertinent information, such as how to send data back to the server.

Network Save: Saves file to a webserver. Note that the functionality provided is equivalent to submitting a form - the backend capability of processing the form data must be provided separately.
1. Choose Network Save Options from the File menu.
2. Set the server to the page that will receive the file upload in the first box. For example http://www.dklevine.com/workshops/testup.php3
3. Set the variables that will be transmitted in the bottom box. Each variable is entered on a separate line in the form variable_name=variable_value. For example

account=george
password=monkey
infile=$$jarnal

When you choose Network Save from the File menu, this will result in the jarnal file you are editing being uploaded under the name infile, and additional variables named account and password being uploaded with values set equal to george and monkey. If the server returns information, you can view it by choosing Show Server Message from the file menu; this information is also echoed to the console, if you have started Jarnal from one.

4. In place of a fixed variable_value such as george, you can use special values beginning with $ to represent internal values from Jarnal. Supported variables are

$$jarnal the contents of the jarnal file
$$snapshot a jpg file with a snapshot of the current page of the jarnal file
$$pdf a pdf file with the entire jarnal file printed according to print options
$f the local name of the jarnal file or unsaved.jaj if the file has not yet been saved locally; when using multipart/form-data it is this parameter that is passed as the filename not $g
$p fully qualified pathname of the jarnal file
$n number of pages in the jarnal file
$u a unique identifer, guaranteed not to change as long as the file remains open and is not saved under another name; can be used so that the server can identify the same file being repeatedly saved
$g the network save name suggested by the user

5. To perform the upload choose Network Save from the File menu; when running as an applet you can also use the Save button.

Using Network Save With Java Servlets: Data uploaded to the server is by default uploaded as binary multipart/form-data, that is as MIME. Java servlets do not decode MIME, they expect POST data to be urlencoded. There is a network save option URLEncode that you can check, or provide in a metadata file, that will force Jarnal to upload using urlencoding. The variable representing the file will be filled with a (rather long) ascii string consisting of base64 data which you must then decode to get the file. There is an undocumented urldecoder that ships with Java that you may wish to use to decode. The Jarnal source code also contains a public source urldecoder from Robert W. Harder in the Jtools.java file. An alternative (thanks to Walter Yuan for this) is to get the com.oreilly.servlet package which supports multipart decoding. You should easily be able to locate the package using google. You can then use it to decode the default MIME uploaded by Jarnal. This is the recommended method, since base64 encoding both adds overhead and significantly increases the number of bytes that must be transmitted. Here is Walter's source code for a sample servlet showing how to use the com.oreilly.servlet package; it accepts MIME encoded upload and echoes them back to the user.

Sample PHP Backend Application: This small application enables you to dedicate a directory in which to store network accessible .jaj files, and create and save new ones. When called without any parameters, it will show you a list of files in the directory, plus the option of creating a new file. Clicking on a file will load the file into Jarnal, and set network save parameters so that when the file is saved by clicking on the Network Save button or choosing Network Save, it replaces the original file, or in the case of a new file, will prompt you to give the file a name. Reloading the original list in your browser will show a list with the new file. Please note that this sample application provides no security whatsoever: if you use it, anyone in the world who can access this application can access your .jaj files.

1. Create  directory accessible to your webserver to keep your .jaj files in.

2. Put the file template.jaj, editing it if you wish, in that directory. template.jaj will prompt for a name on network save and the save button is set to do a network save.

3. Edit the PHP source file to point it to the appropriate directories and files, as indicated in the source code. Improved/fixed PHP source file from Colton Smith. The older version required that globals be registered - this is often turned off, and as PHP 6 will be turned off forever.

4. Place the PHP source file in a directory on your webserver from which PHP scripts can run.

5. Make sure that you have associated the mimetype application/jarnal-meta with java -jar jarnal.jar -m