hades.manager
Class DesignManager

java.lang.Object
  hades.manager.DesignManager

public class DesignManager

extends java.lang.Object

DesignManager - the central HADES design manager class. The singleton instance of this class is responsible for loading, saving, and browsing of simulation models, Designs, and their symbols. DesignManager accesses designs and design resources from local files, JAR/Zip-files, URLs, and the Java classpath.

This class currently supports the following use-cases and scenarios:

• Selecting a file or URL name, either for reading or writing ("SELECT"): This displays a dialog window and prompts the user to select a resource file. It allows to preset a file/URL name, uses a FilenameFilter when appropriate, and takes the default mode (load or save). When closed, the dialog returns a String with the selected file name, or null when canceled.
• Saving a new design ("SAVE AS"): Prompt the user for a file/URL name for the current Hades design (".hds"), then get an OutputStream to write the data.
• Saving design or SimObject resource data ("SAVE AS"): Prompt the user for a file/URL name for the data in question (e.g. ROM initialization data, with a ".rom" extension), then get an OutputStream to write the data. This method will use the file/URL name in its raw form, e.g. an absolute path name. No automatic conversion to relative or classpath-based resource names is done here.
• Creating a symbol for the current design ("SAVE SYMBOL"):
• Selecting and loading an existing design ("SELECT AND LOAD"): Prompt the user to select an existing design file/URL name, then get an InputStream for the design and load it.
• Loading an existing design file ("LOAD"): Given an absolute or relative file name, an URL, or a ZIP/JAR/CLASSPATH resource name, get an InputStream for the design and load it. In hierarchical designs, also use the information about the parent/toplevel design file/URL name to locate subdesigns. This function tries to be as error-tolerant as possible, even trying to recurse into local directories in order to find design files.
• Loading a SimObject or design file resource ("LOAD"): Load design resource files, e.g. RAM/ROM initialization data, stimuli data, image data, SimObject symbol files, FIG files in symbols, microcontroller configuration data, etc. This method locates resources from absolute or relative file names, URLs, ZIP/JAR/CLASSPATH resources, and tries to be as error-tolerant as possible. When necessary, this method tries to complete relative file names via trying combinations with the parent design or toplevel design names.
• Loading an Image or image thumbnail: The same as loading a resource, but relying on jfig ImageHelper or AWT Toolkit to create an Image object from the raw image data.
• Loading SimObjects ("SIMOBJECT"): Load a SimObject from either a given a Java class name (hades.models.gates.And3), or a file/URL name. The latter requires the use of an user-defined ClassLoader and is not implemented yet (import the Colibri stuff here).
• Versioning when writing data ("CHECK-EXISTS-RENAME"): Given a file/URL/resource name, check whether the requested location already exists. If so, automatically rename the existing data, before writing the new data.
• Check when overwriting existing files ("CHECK-EXISTS-OVERWRITE"): Given a file/URL/resource name, check whether the requested location is exists. If so, display a dialog to prompt the user to overwrite the exisiting data or to cancel the operation.
• ConvertToRelativeOrResourceNames ("CONVERT"): Given an existing top-level design file, load that design and convert all absolute file names used in subdesigns or SimObject resources to relative names (relative to the top-level design). If used with an appropriate directory structure for the subdesigns and (sub-)design resources, this allows to move a complete hierarchical design to other directories or other machines. Alternatively, convert all file names to Java classpath resource names, allowing to load a design from the Java classpath.
• If the variable "matlabPath" is set, DesignManager.getInputStream() will search for the input stream using a Matlab-style algorithm in all directories specified on the matlabPath; the first matching stream will be returned. Fully qualified pathnames and URLs including the protocol part can also be used in Matlab-mode.

Nested Class Summary

(package private) class

DesignManager.SwingFileChooser

Method Summary

static java.lang.String	changeExtension(java.lang.String source, java.lang.String newExtension) change the extension of original filename "source" to the "newExtension".
java.lang.String	checkAndAddFilenameExtension(java.lang.String name, java.lang.String extension) utility method to "repair" a missing filename extension.
boolean	checkExistsMakeBackup(java.lang.String pathname) this method checks whether the file/URL specified by "pathname" already exists.
static void	dbg(java.lang.String msg)
static void	dumpTokens(java.lang.String[] tokens)
static java.lang.String	getAbsoluteFilename(java.lang.String pathname)
static java.lang.String	getAppletBaseDir()
static java.lang.String	getAppletServerName()
SimObject	getCopy(SimObject source, Editor editor)
boolean	getDebug()
Design	getDesign(Editor editor, java.lang.String resourcename, boolean toplevel) getDesign: try to load a Design from file/URL "resourcename".
static DesignManager	getDesignManager() Return a reference to the Singleton DesignManager.
static java.lang.String	getDirectory(java.lang.String pathname)
static java.lang.String	getExtension(java.lang.String pathname) get the extension (starting with the last "." dot char) of this pathname, or null.
java.awt.Image	getImage(java.lang.Object parent, java.lang.String pathname) Try to load an Image from the resource called 'pathname'.
java.io.InputStream	getInputStream(java.lang.Object parent, java.lang.String pathname) getInputStream: this method is the heart of DesignManager.
java.lang.String[]	getMatlabPath()
static java.lang.String	getName(java.lang.String pathname)
Design	getNewDesign(Editor editor)
java.io.OutputStream	getOutputStream(java.lang.Object o, java.lang.String pathname)
java.io.InputStream	getResourceAsStream(java.lang.String resourceName) try to find and open an InputStream for the given resource name.
SimObject	getSimObject(java.lang.String classname) getSimObject(): given a Java classname like "hades.models.gates.And2", return an instance of that class.
SimObject	getSimObject(java.lang.String classname, long version, Editor editor) getSimObject(): locate and return a simulation model of class 'classname' and version 'version' or higher.
java.awt.Image	getThumbnail(java.lang.String pathname) load, create and return an Image object from file/URL pathname.
java.io.InputStream	getVirtualFile(java.lang.String key)
java.util.Hashtable	getVirtualFiles()
java.io.InputStream	getZipEntryInputStream(java.lang.String pathname) given a pathname of the form "zip://hugo.zip?/path/to/file.hds" locate the corresponding zipfile (which should have been registered by calling registerZipFile), and return an InputStream for the specified zip entry.
void	msg(java.lang.String msg)
java.io.ByteArrayOutputStream	readStreamIntoBuffer(java.io.InputStream input)
java.io.ByteArrayOutputStream	readStreamIntoBuffer(java.lang.String pathname) find the specified resource and read its contents into a ByteArrayOutputStream buffer.
java.lang.String	readStreamIntoString(java.lang.String pathname) an utility method to read the specified resource into a (multiline) String for further processing.
void	registerZipFile(java.util.zip.ZipFile zipfile)
void	saveAsVirtualFile(java.lang.String key, java.io.InputStream is)
void	saveAsVirtualFile(java.lang.String key, java.lang.String data)
java.lang.String	selectFileOrURLName(java.lang.String dialogTitle, java.lang.String defaultName, java.lang.Object _extensions, int mode) selectFileOrURLName: prompt the user for a file or URL name.
java.lang.String	selectURLName(java.lang.String dialogTitle, java.lang.String defaultName)
static void	setAppletBaseDir(java.lang.String name)
static void	setAppletServerName(java.lang.String servername)
void	setDebug(boolean b)
void	setDialogWindowsParentFrame(java.awt.Frame frame) set a Frame which is used as a parent window for the FileDialog and SelectURLDialog windows.
void	setFileDialogDirectoryAndFilename(java.awt.FileDialog fileDialog, java.lang.String resourceName) try to split resourceName (which always uses '/' as a separator char) into directory and filename parts.
void	setMatlabPath(java.lang.String s)
java.lang.String	toString()
(package private) void	traceResourceAccess(java.lang.String resourceName)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getDesignManager

public static DesignManager getDesignManager()

Return a reference to the Singleton DesignManager.

setMatlabPath

public void setMatlabPath(java.lang.String s)

getMatlabPath

public java.lang.String[] getMatlabPath()

getSimObject

public SimObject getSimObject(java.lang.String classname)
                       throws SimObjectNotFoundException

getSimObject(): given a Java classname like "hades.models.gates.And2", return an instance of that class.

Throws:

SimObjectNotFoundException - if the requested Object is not found

getSimObject

public SimObject getSimObject(java.lang.String classname,
                              long version,
                              Editor editor)
                       throws SimObjectNotFoundException,
                              SimObjectVersionNotFoundException

getSimObject(): locate and return a simulation model of class 'classname' and version 'version' or higher.

The current preliminary implementation just ignores the requested version number!

Throws:

SimObjectNotFoundException - if the Object specified by classname and version number cannot be found

SimObjectVersionNotFoundException - if the version of SimObject cannot be found

getCopy

public SimObject getCopy(SimObject source,
                         Editor editor)

getNewDesign

public Design getNewDesign(Editor editor)

getDesign

public Design getDesign(Editor editor,
                        java.lang.String resourcename,
                        boolean toplevel)
                 throws SimObjectNotFoundException

getDesign: try to load a Design from file/URL "resourcename". Set "toplevel" true for toplevel (visible) designs, and to false for subdesigns.

Throws:

SimObjectNotFoundException

checkExistsMakeBackup

public boolean checkExistsMakeBackup(java.lang.String pathname)

this method checks whether the file/URL specified by "pathname" already exists. If so, it renames the original file to a backup name.

Note that the current implementation only works for local files, not for remote files or URLs, and not for files in JAR/Zip archives.

At the moment, the backup name is constructed by appending an underscore character and an integer. For example, the backups for Hades design "/examples/cla/adder8.hds" will be called "/examples/cla/adder8.hds_1", "/examples/cla/ader8.hds_2", and so on. We use the trivial algorithm for this, which becomes very slow when the number of existing backup files is large.

Returns:

a flag indicating whether we created a backup

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String resourceName)

try to find and open an InputStream for the given resource name.

traceResourceAccess

void traceResourceAccess(java.lang.String resourceName)

getAppletServerName

public static java.lang.String getAppletServerName()

setAppletServerName

public static void setAppletServerName(java.lang.String servername)

getAppletBaseDir

public static java.lang.String getAppletBaseDir()

setAppletBaseDir

public static void setAppletBaseDir(java.lang.String name)

setDialogWindowsParentFrame

public void setDialogWindowsParentFrame(java.awt.Frame frame)

set a Frame which is used as a parent window for the FileDialog and SelectURLDialog windows.

selectFileOrURLName

public java.lang.String selectFileOrURLName(java.lang.String dialogTitle,
                                            java.lang.String defaultName,
                                            java.lang.Object _extensions,
                                            int mode)

selectFileOrURLName: prompt the user for a file or URL name. This method will return the null value if the user cancels the selection. Other typical return values might be "adder16.hds", "http://www.some.server.org/path/data.rom" or "file://home/joe.user/foo/bar.jpeg". Note that this method will replace the platform-dependent separator char (e.g. the backslash '\' used by Windows) in a selected filename with normal '/' slashes.

If non-null, dialogTitle is used for dialog window title, defaultName is used as the initial file/URL name, and the extension is used to create a matching hades.utils.EndsWithFilter. The mode argument should be either java.awt.FileDialog.LOAD or java.awt.FileDialog.SAVE.

The current implementation uses AWT-based dialog windows (FileDialog and hades.gui.SelectURLDialog), but this will use the BrowserFrame JTree-based selection soon.

Question: Why does the JDK deadlock or crashes on Windows, when this method is made synchronized?

selectURLName

public java.lang.String selectURLName(java.lang.String dialogTitle,
                                      java.lang.String defaultName)

setFileDialogDirectoryAndFilename

public void setFileDialogDirectoryAndFilename(java.awt.FileDialog fileDialog,
                                              java.lang.String resourceName)

try to split resourceName (which always uses '/' as a separator char) into directory and filename parts. Check that the resulting directory name denotes an existing directory. If so, set the directory and filename in the fileDialog.

checkAndAddFilenameExtension

public java.lang.String checkAndAddFilenameExtension(java.lang.String name,
                                                     java.lang.String extension)

utility method to "repair" a missing filename extension. Use this method to add the filename extension expected by Hades, when the platform file dialog ignores FileNameFilter and the user did not explicitly specify a filename extension.

This method will first check the current value of the SetupManager "Hades.DesignManager.AutoAddExtension" property. If not true, the method returns the original "name" argument unmodified. When enabled, this method will then check whether the string "name" already has an extension. If yes, it also returns the original string. If not, it will add "extension" to "name".

For example, when called with "c:\tmp\adder" and ".hds" arguments, this method will return "c:\tmp\adder.hds".

This is a dumb method, the check for an extension is made simply by searching for a dot "." in the original "name". This algorithm is not optimal when the user selects a name with multiple dots in it.

getInputStream

public java.io.InputStream getInputStream(java.lang.Object parent,
                                          java.lang.String pathname)

getInputStream: this method is the heart of DesignManager. It tries to find the specified resource as error-tolerant as possible and returns an InputStream for further processing. It searches a variety of sources: local files, URLs, CLASSPATH resources (zip://, file://, http://, resource:, local files). Some examples for the supported pathnames:

     file://c:/users/foo/examples/bar.txt
     zip://c:/temp/foo.zip?/foo/foo2/foobar.hds
     virtual://hashtable-key.hds
     hades/models/gates/And2.gif
     /hades/models/gates/And2.gif
     resource://hades/models/io/Ipin.sym
     ./foobar.rom
     

When searching for a local file, this method will automagically replace any slash chars ('/') in pathname with the platform dependent separator char.

When the first argument is non-null, it will also be used to search for the given resource. For example, when the first argument is a Hades Design, that Design resource name will be used to search for pathname, too.

When matlabPath is non-null, getInputStream() employs a Matlab-style algorithm: every directory on the matlabPath array is searched for the given (relative) path, and the first matching stream is returned.

dumpTokens

public static void dumpTokens(java.lang.String[] tokens)

getOutputStream

public java.io.OutputStream getOutputStream(java.lang.Object o,
                                            java.lang.String pathname)

getThumbnail

public java.awt.Image getThumbnail(java.lang.String pathname)

load, create and return an Image object from file/URL pathname. As we expect the Image to be small and to be re-used, we cache the Images in an internal Hashtable, to speed up future accesses to the same Image. We delegate the actual image loading to getImage( String pathname )... If the requested Image cannot be found, we try to return the "/hades/manager/icons/null.gif" icon instead.

getImage

public java.awt.Image getImage(java.lang.Object parent,
                               java.lang.String pathname)

Try to load an Image from the resource called 'pathname'. The first argument (which might be null) allows to specify a context for the pathname. If the Image cannot be found, or cannot be decoded, we return null. We use a timeout of at most 10000 msec before returning.

The raw image data is loaded via DesignManager.getInputStream() into a ByteArrayOutputStream, and then converted into an Image via java.awt.Toolkit.createImage().

readStreamIntoString

public java.lang.String readStreamIntoString(java.lang.String pathname)

an utility method to read the specified resource into a (multiline) String for further processing. This method returns null when the resource 'pathname' cannot be found.

readStreamIntoBuffer

public java.io.ByteArrayOutputStream readStreamIntoBuffer(java.lang.String pathname)

find the specified resource and read its contents into a ByteArrayOutputStream buffer. This method returns null when the resource 'pathname' cannot be found. Internally, this method uses getInputStream( null, pathname ) to locate the resource.

readStreamIntoBuffer

public java.io.ByteArrayOutputStream readStreamIntoBuffer(java.io.InputStream input)

getVirtualFiles

public java.util.Hashtable getVirtualFiles()

saveAsVirtualFile

public void saveAsVirtualFile(java.lang.String key,
                              java.io.InputStream is)

saveAsVirtualFile

public void saveAsVirtualFile(java.lang.String key,
                              java.lang.String data)

getVirtualFile

public java.io.InputStream getVirtualFile(java.lang.String key)

registerZipFile

public void registerZipFile(java.util.zip.ZipFile zipfile)

getZipEntryInputStream

public java.io.InputStream getZipEntryInputStream(java.lang.String pathname)

given a pathname of the form "zip://hugo.zip?/path/to/file.hds" locate the corresponding zipfile (which should have been registered by calling registerZipFile), and return an InputStream for the specified zip entry.

getAbsoluteFilename

public static java.lang.String getAbsoluteFilename(java.lang.String pathname)

getDirectory

public static java.lang.String getDirectory(java.lang.String pathname)

getName

public static java.lang.String getName(java.lang.String pathname)

getExtension

public static java.lang.String getExtension(java.lang.String pathname)

get the extension (starting with the last "." dot char) of this pathname, or null. For example, called with "/tmp/hades/adder.hds", this method will return ".hds".

changeExtension

public static java.lang.String changeExtension(java.lang.String source,
                                               java.lang.String newExtension)

change the extension of original filename "source" to the "newExtension". If the original name has no extension at all, add the new extension. The extension is interpreted as the part of a name beginning with the last "." dot char.

For example, calling this method with arguments "/tmp/design/traffic.hds" and ".sym" will create the name "/tmp/design/traffic.sym". This dumb method is not designed to handle illegal or null arguments.

setDebug

public void setDebug(boolean b)

getDebug

public boolean getDebug()

dbg

public static void dbg(java.lang.String msg)

msg

public void msg(java.lang.String msg)

toString

public java.lang.String toString()