7 Web Collaboration Appendix

This is an archived version, please use the menu on the left, or jump to the new version: 7.00 Appendix

7.1 Appendix A: A full example of a preference file

#---Program wide Preferences (properties)---
#Location = Jar:/Preference/

CollaborationJarPreferences = Loaded

## Default systems for the storage and display locations
Collaboration.storage = File.YEdit
#Collaboration.storage = File.Server
#Collaboration.storage = File.localhost

Collaboration.export = Export.YEdit
Collaboration.display = Console.null

## File system storage
Collaboration.File.YEdit.BaseDir = /usr/home/yedit/revisions/
Collaboration.File.Server.BaseDir = /home/drhean/yedit/revisions/
Collaboration.File.localhost.BaseServer = D
Collaboration.File.localhost.BaseDir = \\Software\\Java\\revisions\\
#
FactoryAccess.File.YEdit = com.YEdit.ServerInterface.FileSystem.FileSystem
FactoryAccess.File.Server = com.YEdit.ServerInterface.FileSystem.FileSystem
FactoryAccess.File.localhost = com.YEdit.ServerInterface.FileSystem.FileSystem

## Static web site location
Collaboration.webStatic = www.YEdit.com
#Collaboration.webStatic = Server
#Collaboration.webStatic = localhost

## Dynamic web site location
Collaboration.webDynamic = www.YEdit.com
#Collaboration.webDynamic = Server
#Collaboration.webDynamic = localhost

## Email
Collaboration.email = ...@YEdit....
#Collaboration.email = ...@massey....

## Servlet dir location
Collaboration.servlets = /servlets

## Location of the Server Home directory
Collaboration.ServerDir = /usr/home/yedit/
#Collaboration.ServerDir = /home/drhean/yedit/
#Collaboration.ServerDir = D:/SOFTWARE/JAVA/

##File system for Revisions (from the Server dir)
Collaboration.revisionDir = revisions/

## Location to save all the survey information (from the Server dir)
Collaboration.surveySaveDir = surveys/

## Error/Debug log file (from the Server dir)
Collaboration.log = surveys/log.log

## Location of the WWW Home directory
Collaboration.wwwHomeDir = /usr/home/yedit/www/
#Collaboration.wwwHomeDir = /home/drhean/yedit/www/
#Collaboration.wwwHomeDir = D:/SOFTWARE/JAVA/htdoc.YEdit/

## Filename of the 404 page (from the WWW Home dir)
Collaboration.page404 = missing.html

## Filename of the New (Add) page (from the WWW Home dir)
Collaboration.newPage = new.html

## Directory to store the newest export version
Collaboration.Export.YEdit.BaseDir = /usr/home/yedit/www/public/
Collaboration.Export.Server.BaseDir = /home/drhean/yedit/www/public/
Collaboration.Export.localhost.BaseServer = D
Collaboration.Export.localhost.BaseDir = /SOFTWARE/JAVA/htdoc.YEdit/public/
#
FactoryAccess.Export.YEdit = com.YEdit.ServerInterface.FileSystem.FileSystem
FactoryAccess.Export.Server = com.YEdit.ServerInterface.FileSystem.FileSystem
FactoryAccess.Export.localhost = com.YEdit.ServerInterface.FileSystem.FileSystem


7.2         Appendix B: Using YEdit

Reading a file using YEdit

The following extract from the "Read" servlet demonstrates reading the latest version of a file, and returning it as a string that is then sent to the web browser.  The parameter passed as "USL file" is the location of the file that is to be read.

"Web.storageSystem" is the type of file system that is in use.  This is read from the preference (initialisation) file.

public static String read( USL file)
  {
  com.YEdit.Interface.IAccess storageObj  = null;
  BufferedInputStream bufIn = null;
  int c = 0;
  StringBuffer output = new StringBuffer();
  PrintWriter out = null;


Up to here is just the setting up of the variables.  The following line creates an object using the correct class (as defined in the preference file) to access the file storage system that is in use.

  storageObj = com.YEdit.Interface.FactoryCreate.access( Web.storageSystem, file);

The following "if" checks to see if a specific version is wanted, if not, it retrieves the latest version.

  if( null == file.getVersion() )
    {  // Get the latest version
    storageObj = com.YEdit.Interface.FactoryCreate.access( Web.storageSystem, file.dupVersion( storageObj.highestRevision()));
    }


Now that the correct version has been located, it is read in.  If there is an error, the error is logged and a blank file is returned.

  try {
    bufIn = new java.io.BufferedInputStream( storageObj.getInputStream());
    while ((c = bufIn.read()) != -1)
      {
      output.append((char)c);
      }
    bufIn.close();
    }
  catch (IOException e)
    {// File not found
    Log.error(e, "File not found: " + storageObj.getUSL() );
    out = null;
    return(null);
    }


The file is returned as a string, ready to be passed to the web browser.

  bufIn = null;
  return(output.toString());
  }


 

Writing a file using YEdit

The following is extracted from the Edit servlet, from where it saves the edited file.

  {
  USL outUSL = null;
  String fileText = null;
  IVersion oldFileVersion = null;
  com.YEdit.Interface.IAccess storageObj  = null;
  String user = null;
  String email = null;


The above code sets up some of the variables that are used.

"outUSL" is the location of the file to be saved.
"fileText" is the text of the file to be saved.
"oldFileVersion" is the version of the file when it was read (0 if it is a new file).
"email" is the user's name or email address

The following code opens the file to be saved, checks that the version that has been edited is the same as the current version (so as not to overwrite any other changes), and then saves it.

  storageObj = com.YEdit.Interface.FactoryCreate.access( Web.storageSystem, outUSL);
  if( storageObj.highestRevision().equals( oldFileVersion) )
    {  // The edited document version matches the most recent document
    user = request.getRemoteUser();
    if( null == user )
      { user = "Public"; }
    if( null != email )
      { user = user + ": " + email; }
    storageObj = com.YEdit.Interface.FactoryCreate.access( Web.storageSystem, outUSL.dupVersion( oldFileVersion.next()));
    if( storageObj.lock( user, "Web") )
      {
      try {
        storageObj.print(fileText);
        storageObj.unlock();

        // File saved


The file has been successfully saved, therefore success is reported to the user at this point, and control is returned.

        return;
        }

      catch(IOException e)
        {
        // Error writing to the file


An error occurred when writing to the file; it may not have been saved.  A warning is displayed to the user at this point, and control is returned.

        return;
        }
      }
    else{
      // Error locking the file


The file could not be locked; maybe it is in use by someone else?  A warning is displayed to the user at this point, and control is returned.

      return;
      }
    }
  else{// The edited document and most recent document do NOT match
    // This means that someone else has edited and saved the document


The document has been updated by someone else, so a message asking the user to please merge both sets of changes into one and save the results is displayed.

    }
  }


 

Accessing the file storage system

The following code is extracted from the class "com.YEdit.Interface.FactoryCreate" to demonstrate how the correct storage system is loaded, and to show that it returns a class that conforms to the Java Interface "IAccess", which is the middle interface, this is shown in the next appendix.

public static final IAccess access(String type, USL fileObject)
  {
  String classNamePrefs = null;
  MasterPreference prefs;
  IAccess file = null;
  StringBuffer className = new StringBuffer("FactoryAccess.");
  className.append(type);


Sets up the variables and creates the name of the preference that holds the correct class to load (for example on YEdit.com "File.YEdit" is passed into this method).

  try {
    // Only load the default, system, and user system preferences
    prefs = MasterPreference.instance();

    classNamePrefs = prefs.getPreference( className.toString());
    // Check that it was found
    if( null == classNamePrefs )
      {
      Log.fatalError("Error: Could not find '" + className.toString() + "' in the system preferences.");
      }


The code above retrieves the name of the class that is used for the type of file storage system passed.  Once that is known, an object is created that contains that class, which is set up with the name of the file to use, and then the object is passed back to the calling code.  The object that is returned uses the Java Interface "IAccess" to give access to the internal methods.

    file = (IAccess)Class.forName(classNamePrefs).newInstance();
    file.setUSL(fileObject);
    }
  catch(Exception e)
    {
    Log.error(e, "ERROR: Instantiating " + classNamePrefs + " from factory.");
    file = null;
    }
  return( file );
  }


7.3         Appendix C: The Middle Interface

The middle interface has two parts.  The first part is the Java Interface that is called "com.YEdit.Interface.IAccess".  This Java Interface defines the methods that are implemented in order to allow access to the server interface for support of the requests that may be made.  The second part is the super class called "com.YEdit.Interface._Access".  This is an optional super class for any of the access factory classes.  This super class assigns default behaviour to many of the methods and it allows one place for code that may be repeated in each sub-class.

com.YEdit.Interface

public abstract interface IAccess

An interface that defines the methods that are implemented in order to assure and enable consistent access to them.  These classes must be able to stand-alone, that is they only rely on standard classes that are guaranteed to be present.

 
Copyright: Copyright (c) Daniel Hean 1998-2000, all rights reserved.
Date:      7 March 2000
Version:   alpha 0.2000.03.7
Author:    Daniel Hean

Method Detail

public java.lang.String[] list()

Returns a list of the files in the directory specified by this object.

public java.lang.String[] list( java.io.FilenameFilter filter)

Returns a list of the files in the directory specified by this object that satisfy the specified filter.

public boolean mkdir()

Creates a directory whose path name is specified by this object.

public boolean mkdirs()

Creates a directory whose path name is specified by this object, including any necessary parent directories.

public void setUSL( com.Inishgold.USL.USL valueUSL)

Set the internal value that stores the information source that we are currently looking at.

public com.Inishgold.USL.USL getUSL()

Return the USL of the current file.

public long getExpiration()

Returns the value of the expires header field.

public long lastModified()

Returns the time that the object was last modified.

public java.lang.String lastModifiedBy()

Returns who last modified the object.

public long length()

Returns the length of the file represented by this object.

public java.lang.String getReadWriteAccess()

Returns the read, write and execute permissions for this file.

public boolean exists()

Tests if this File exists.

public boolean canRead()

Tests if the application can read from the specified file.

public boolean canWrite()

Tests if the application can write to this file.

public com.Inishgold.USL.IVersion highestRevision()

Return the latest revision number for this file (Do not cache, unless all possible changes are caught).

public boolean lock( java.lang.String userName, java.lang.String location)
throws java.io.IOException

Lock the object so that it is possible to read from and update the information pointed to by the object.  This allows only one person to have an open output stream at any time.

public void unlock()

Release the write lock and close the stream, so that others can write to it and by closing the stream, it ensures that we can't mistakenly write to it again, even if we have stored the stream.

public boolean isLocked()

Check to see if the object is currently locked.

public java.lang.String getLockedWhenStr()

Retrieve the time that this was locked (in String format).

public java.io.InputStream getInputStream()
throws java.io.IOException

Retrieve the stream to use for input from this resource.

public java.io.OutputStream getOutputStream()
throws java.io.IOException

If the output stream is locked this will return the stream to use, if it is not currently locked, this must throw an IOException.  Note: When the stream is unlocked, the stream that is given by this method will be closed, so as to avoid unlocked writes.

public java.io.OutputStream getErrorStream()
throws java.io.IOException

Retrieve the stream for errors related to this object, this should always be available.

public java.io.PrintWriter getErrorWriter()
throws java.io.IOException

Retrieve the PrintWriter for errors related to this object, this should always be available.

public void print( java.io.InputStream in)
throws java.io.IOException

Write the contents of the supplied InputStream to the current object's OutputStream.

public void print( java.lang.String in)
throws java.io.IOException

Write the contents of the supplied String to the current object's OutputStream.

public void println( java.lang.String in)
throws java.io.IOException

Write the contents of the supplied String to the current object's OutputStream adding a newline to the end.

public boolean delete()

Deletes the file specified by this object.

public boolean renameTo( com.Inishgold.USL.USL name)

Renames the file specified by this object to have the path name given by the supplied argument.

 

com.YEdit.Interface

public abstract class _Access
extends java.lang.Object
implements IAccess

The _Access class is the optional super class of any access factory classes.  It is optional to use this class as a super class for the access factory classes because all the required methods are defined in the interface (IAccess).  The reason to use this as a super class is to organise in one place the methods that are repeatedly written in each access factory class.

 
Copyright: Copyright (c) Daniel Hean 1998-2000, all rights reserved.
Date:      17 May 2000
Version:   alpha 0.2000.05.17
Author:    Daniel Hean

Constructor Detail

protected _Access()
throws java.io.IOException

Method Detail

public boolean isLocked()

Check to see if the object is currently locked.
Specified by: isLocked in interface IAccess

protected abstract boolean setLockedWhoLoc( java.lang.String who, java.lang.String location)

Set the name of the person who has this resource locked for writing.  If the underlying resource is locked, then return false to signify that the lock failed.  This must never be called directly, not even by this class.

public abstract java.lang.String getLockedWho()

Retrieve the name of the person who has this resource locked for writing.

public abstract long getLockedWhen()

Retrieve the time that this was locked (in Unix format).

public abstract java.lang.String getLockedWhenStr()

Retrieve the time that this was locked (in String format).
Specified by: getLockedWhenStr in interface IAccess

public boolean lock( java.lang.String who, java.lang.String location)
throws java.io.IOException

Lock the object so that it is possible to read from and update the information pointed to by the object.  This allows only one person to have an open output stream at any time.
Specified by: lock in interface IAccess

public void unlock()

Release the write lock and close the stream, so the others can write to it and by closing the stream, it ensures that we can't mistakenly write to it again, even if we have stored the stream.
Specified by: unlock in interface IAccess

public com.Inishgold.USL.USL getUSL()

Return the USL of the file.
Specified by: getUSL in interface IAccess

public void setUSL( com.Inishgold.USL.USL valueUSL)

Set the internal value that stores the information source that we are currently looking at.
Specified by: setUSL in interface IAccess

public void print( java.io.InputStream in)
throws java.io.IOException

Write the contents of the supplied InputStream to the current object's OutputStream.
Specified by: print in interface IAccess

public void print( java.lang.String in)
throws java.io.IOException

Write the contents of the supplied String to the current object's OutputStream.
Specified by: print in interface IAccess

public void println( java.lang.String in)
throws java.io.IOException

Write the contents of the supplied String to the current object's OutputStream adding a newline to the end.
Specified by: println in interface IAccess

protected abstract java.io.InputStream setInputStream( com.Inishgold.USL.USL file)
throws java.io.IOException

This is to be overridden in the subclass to do the actual creation of the input stream.  This should return this class's inputStream.

protected abstract java.io.OutputStream setOutputStream( com.Inishgold.USL.USL file)
throws java.io.IOException

This is to be overridden in the subclass to do the actual creation of the output stream.  This should return this class's output stream.

protected abstract java.io.OutputStream setErrorStream()
throws java.io.IOException

This is to be overridden in the subclass to do the actual creation of the error stream.  This should return this class's error stream, and it must be available.

public java.io.InputStream getInputStream()
throws java.io.IOException

Retrieve the stream to use for input from this resource.
Specified by: getInputStream in interface IAccess

public java.io.OutputStream getOutputStream()
throws java.io.IOException

If the output stream is locked this will return the stream to use, if it is not currently locked, this must throw an IOException.  Note: When the stream is unlocked, the stream that is given by this method will be closed, so as to avoid unlocked writes.
Specified by: getOutputStream in interface IAccess

public java.io.OutputStream getErrorStream()
throws java.io.IOException

Retrieve the stream for errors related to this object, this should always be available.
Specified by: getErrorStream in interface IAccess

public java.io.PrintWriter getErrorWriter()
throws java.io.IOException

Retrieve the PrintWriter for errors related to this object, this should always be available.
Specified by: getErrorWriter in interface IAccess

public boolean exists()

Tests if this file exists.
Specified by: exists in interface IAccess

public boolean canRead()

Tests if the application can read from the specified file.
Specified by: canRead in interface IAccess

public boolean canWrite()

Tests if the application can write to this file.
Specified by: canWrite in interface IAccess

public long lastModified()

Returns the time that the object was last modified.
Specified by: lastModified in interface IAccess

public java.lang.String lastModifiedBy()

Returns who last modified the object.
Specified by: lastModifiedBy in interface IAccess

public long getExpiration()

Returns the value of the expires header field.
Specified by: getExpiration in interface IAccess

public long length()

Returns the length of the file represented by this object.
Specified by: length in interface IAccess

public java.lang.String getReadWriteAccess()

Returns the read, write and execute permissions for this file.
Specified by: getReadWriteAccess in interface IAccess

public com.Inishgold.USL.IVersion highestRevision()

Return the latest revision number for this file (Do not cache, unless all possible changes are caught).
Specified by: highestRevision in interface IAccess

public boolean delete()

Deletes the file specified by this object.
Specified by: delete in interface IAccess

public boolean renameTo( com.Inishgold.USL.USL name)

Renames the file specified by this object to have the path name given by the supplied argument.
Specified by: renameTo in interface IAccess

public java.lang.String[] list()

Returns a list of the files in the directory specified by this object.
Specified by: list in interface IAccess

public java.lang.String[] list( java.io.FilenameFilter filter)

Returns a list of the files in the directory specified by this object that satisfy the specified filter.
Specified by: list in interface IAccess

public boolean mkdir()

Creates a directory whose path name is specified by this object.
Specified by: mkdir in interface IAccess

public boolean mkdirs()

Creates a directory whose path name is specified by this object, including any necessary parent directories.
Specified by: mkdirs in interface IAccess

7.4         Appendix D: The Server Interface (File System example)

com.YEdit.ServerInterface.FileSystem

public class FileSystem
extends _Access
implements IAccess

The FileSystem class is the factory access class that controls access to the systems file system.

Note: The reason that this does not subclass the applicable File/JDBC classes is because that would expose methods and variables that are not consistent across those different classes.  That would mean that these classes would no longer be modular as they have been designed, and you would no longer be able to just plug in the one you want and use it.

 
Copyright: Copyright (c) Daniel Hean 1998-2000, all rights reserved.
Date:      17 Sept 2000
Version:   alpha 0.2000.09.17
Author:    Daniel Hean

Constructor Detail

public FileSystem()
throws java.io.IOException

Method Detail

protected boolean setLockedWhoLoc( java.lang.String who, java.lang.String location)

Set the name of the person who has this resource locked for writing.  If the underlying resource is locked, then return false to signify that the lock failed.  This must never be called directly, not even by this class.
Overrides: setLockedWhoLoc in class _Access

public java.lang.String getLockedWho()

Retrieve the name of the person who has this resource locked for writing.
Overrides: getLockedWho in class _Access

public java.lang.String getLockedLocation()

Retrieve the location that this was locked from.

public long getLockedWhen()

Retrieve the time that this was locked (in Unix format).
Overrides: getLockedWhen in class _Access

public java.lang.String getLockedWhenStr()

Retrieve the time that this was locked (in String format).
Specified by: getLockedWhenStr in interface IAccess
Overrides: getLockedWhenStr in class _Access

protected java.io.InputStream setInputStream( com.Inishgold.USL.USL file)
throws java.io.IOException

Return the file stream to use for input from this file.
Overrides: setInputStream in class _Access

protected java.io.OutputStream setOutputStream( com.Inishgold.USL.USL file)
throws java.io.IOException

Return the file stream to use for output to this file.
Overrides: setOutputStream in class _Access

protected java.io.OutputStream setErrorStream()
throws java.io.IOException

Return the file stream to use for output to this file's error channel.
Overrides: setErrorStream in class _Access

public boolean exists()

Tests if this file exists.
Specified by: exists in interface IAccess
Overrides: exists in class _Access

public boolean canRead()

Tests if the application can read from the specified file.
Specified by: canRead in interface IAccess
Overrides: canRead in class _Access

public boolean canWrite()

Tests if the application can write to this file.
Specified by: canWrite in interface IAccess
Overrides: canWrite in class _Access

public com.Inishgold.USL.IVersion highestRevision()

Return the latest revision number for this file (Do not cache, unless all possible changes are caught).
Specified by: highestRevision in interface IAccess
Overrides: highestRevision in class _Access

(6 Glossary) Previous

Next (8 References)