ilog.views.prototypes
Class IlvPrototypeLibrary

java.lang.Object
  |
  +--ilog.views.prototypes.IlvPrototypeLibrary

public class IlvPrototypeLibrary

extends Object

implements IlvPersistentObject, Serializable

The class IlvPrototypeLibrary is used to organize, load, and save prototypes.

A prototype library contains a set of prototypes. All the prototypes used in an application are identified by the name of the library to which they belong and by their name. This identification is unique.

Prototype libraries can be automatically loaded when an ILOG JViews file containing prototype instances is read. This means that an application which just loads panels will not need to use the IlvPrototypeLibrary class directly.

To load a prototype explicitly, you can use the getPrototype method as shown below:

     IlvPrototype proto = 
         IlvPrototypeLibrary.getPrototype("mylib", "myproto");
 

Prototype libraries are saved to normal ILOG JViews files. Library files are searched using a path that you can define with the addToPath method.

The other methods of the class are intended to be used by applications that need to define new prototypes and prototype libraries.

See Also:

IlvPrototype

Constructor Summary

IlvPrototypeLibrary(IlvInputStream in)
Reads a prototype library from a stream.

IlvPrototypeLibrary(String name)
Creates a new prototype library with the specified name.

Method Summary

void	addPrototype(IlvPrototype prototype) Adds a prototype to this library.
static void	addToPath(String dirname) Adds a directory to the path used to locate prototypes.
static void	addToPath(URL url) Adds a URL to the path used to locate prototypes.
static Enumeration	getAllLibraries() Returns all the prototype libraries currently loaded or created.
static IlvPrototypeLibrary	getLibrary(String libName) Loads a prototype library.
String	getName() Returns the name of this library.
static URL[]	getPath() Returns the path used to locate prototype library files.
IlvPrototype	getPrototype(String protoName) Gets the prototype whose name is specified.
static IlvPrototype	getPrototype(String prototypeURL, Class jarClass) Reads a prototype from a URL, or from a JAR archive.
static IlvPrototype	getPrototype(String libName, String protoName) Loads a prototype from a library name and a prototype name.
Enumeration	getPrototypes() Returns the prototypes that this library contains.
URL	getURL() Returns the location from which the library was loaded.
static IlvPrototypeLibrary[]	read(String filename) Reads the prototype libraries contained in an ILOG JViews formatted file.
static IlvPrototypeLibrary[]	read(URL url) Reads the prototype libraries contained in an ILOG JViews formatted file.
static IlvPrototypeLibrary	readCPP(String filename) Reads a prototype library from an ILOG Views formatted file (.ipl).
static IlvPrototypeLibrary	readCPP(URL url) Reads a prototype library from an ILOG Views formatted file (.ipl).
static void	registerEditor(IlvPrototypeLibraryEditor editor) Registers an IlvPrototypeLibraryEditor.
void	removePrototype(IlvPrototype prototype) Removes a prototype from this library.
void	replacePrototype(IlvPrototype oldPrototype, IlvPrototype prototype) Replaces a prototype of this library with a new one.
void	setName(String name) Changes the name of this prototype library.
void	setURL(URL url) Sets the location from which the library was loaded.
void	write(IlvOutputStream out) Writes this prototype library to an output stream.
void	write(String filename) Writes a prototype library to a specified file.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvPrototypeLibrary

public IlvPrototypeLibrary(String name)

Creates a new prototype library with the specified name.

Parameters:

name - the name of the new library.

IlvPrototypeLibrary

public IlvPrototypeLibrary(IlvInputStream in)
                    throws IlvReadFileException

Reads a prototype library from a stream. This method must not be called directly by applications.

Parameters:

in - the input stream.

Throws:

IlvReadFileException - if an I/O error occurs or if the file format is incorrect.

Method Detail

write

public void write(IlvOutputStream out)
           throws IOException

Writes this prototype library to an output stream. This method is public because it is inherited from the IlvPersistentObject interface, but it should not be called directly by applications.

Specified by:

write in interface IlvPersistentObject

Parameters:

out - the output stream.

Throws:

IOException - if an I/O error occurs.

getName

public String getName()

Returns the name of this library.

setName

public void setName(String name)

Changes the name of this prototype library.

Parameters:

name - the new library name.

addPrototype

public void addPrototype(IlvPrototype prototype)

Adds a prototype to this library.

Parameters:

prototype - the prototype to be added.

removePrototype

public void removePrototype(IlvPrototype prototype)

Removes a prototype from this library.

Parameters:

prototype - the prototype to be removed.

replacePrototype

public void replacePrototype(IlvPrototype oldPrototype,
                             IlvPrototype prototype)

Replaces a prototype of this library with a new one.

Parameters:

oldPrototype - the prototype to replace.

prototype - the new prototype to add instead of oldPrototype.

getPrototypes

public Enumeration getPrototypes()

Returns the prototypes that this library contains.

Returns:

an enumeration of IlvPrototype objects.

See Also:

getPrototype(java.lang.String, java.lang.String)

read

public static IlvPrototypeLibrary[] read(URL url)
                                  throws IOException,
                                         IlvReadFileException

Reads the prototype libraries contained in an ILOG JViews formatted file.

This method is intended to be used by GUI editors. Other applications will normally use the getLibrary or getPrototype methods to fetch prototypes.

Parameters:

url - the location of the library file to be loaded.

Returns:

the array of prototype libraries read.

Throws:

IOException - if an I/O error occurs.

IlvReadFileException - if the library file format is wrong.

See Also:

getPrototype(java.lang.String, java.lang.String), getLibrary(java.lang.String)

read

public static IlvPrototypeLibrary[] read(String filename)
                                  throws IOException,
                                         IlvReadFileException

Reads the prototype libraries contained in an ILOG JViews formatted file.

This method creates a URL from the specified file name and calls read(URL).

Parameters:

filename - the file name.

Returns:

the array of prototype libraries read.

Throws:

IOException - if an I/O error occurs.

IlvReadFileException - if the library file format is wrong.

See Also:

read(java.net.URL)

readCPP

public static IlvPrototypeLibrary readCPP(URL url)
                                   throws IOException,
                                          IlvReadFileException

Reads a prototype library from an ILOG Views formatted file (.ipl).

This method is intended to be used by GUI editors. Other applications will normally use the getLibrary or getPrototype methods to fetch prototypes.

Parameters:

url - the location of the .ipl library file to be loaded.

Returns:

the prototype library loaded.

Throws:

IOException - if an I/O error occurs.

IlvReadFileException - if the library file format is wrong.

See Also:

getPrototype(java.lang.String, java.lang.String), getLibrary(java.lang.String)

readCPP

public static IlvPrototypeLibrary readCPP(String filename)
                                   throws IOException,
                                          IlvReadFileException

Reads a prototype library from an ILOG Views formatted file (.ipl).

This method creates a URL from the specified file name and calls readCPP(URL).

Parameters:

filename - the file name.

Returns:

the array of prototype libraries read.

Throws:

IOException - if an I/O error occurs.

IlvReadFileException - if the library file format is wrong.

See Also:

read(java.net.URL)

write

public void write(String filename)
           throws IOException

Writes a prototype library to a specified file.

Parameters:

filename - the file where the library will be saved.

Throws:

IOException - if an I/O error occurs.

getLibrary

public static IlvPrototypeLibrary getLibrary(String libName)
                                      throws IlvReadFileException

Loads a prototype library.

If the prototype library specified is not already loaded, its file is searched for in the prototype search path (for details, see the addToPath methods). The prototype library file has the .ilv extension (libName.ivl) and is located in the directory or in the subdirectory indicated in the path (for example, libName/libName.ivl).

If the file of the prototype library is found, it is read with the read method, and all the prototypes contained in the file are stored in the library.

This method can also load ILOG Views (C++) prototype libraries (.ipl files). If no ILOG JViews file is found for a given prototype library, an ILOG Views file is searched for using the same procedure.

Parameters:

libName - the name of the prototype library.

Returns:

the prototype library.

Throws:

IlvReadFileException - if the library file could not be found.

See Also:

addToPath(java.net.URL), addToPath(java.lang.String)

getPrototype

public static IlvPrototype getPrototype(String libName,
                                        String protoName)
                                 throws IlvReadFileException

Loads a prototype from a library name and a prototype name.

If required, this method calls getLibrary to load the library. Then it calls getPrototype to get the prototype specified.

Parameters:

libName - the name of the prototype library.

protoName - the name of the prototype.

Throws:

IlvReadFileException - if the library or the prototype could not be found.

getPrototype

public IlvPrototype getPrototype(String protoName)

Gets the prototype whose name is specified.

Parameters:

protoName - the name of the prototype.

Returns:

the prototype whose name is specified, or null if it does not exist or if it could not be loaded.

addToPath

public static void addToPath(URL url)

Adds a URL to the path used to locate prototypes.

Parameters:

url - the URL to be added to the prototype access path.

addToPath

public static void addToPath(String dirname)
                      throws MalformedURLException

Adds a directory to the path used to locate prototypes.

Parameters:

dirname - the directory to be added to the prototype access path. The directory name must end with a path separator (slash or backslash).

Throws:

MalformedURLException - if the directory name could not be translated to a valid URL.

getPath

public static URL[] getPath()

Returns the path used to locate prototype library files.

registerEditor

public static void registerEditor(IlvPrototypeLibraryEditor editor)

Registers an IlvPrototypeLibraryEditor. This object will be notified every time a new prototype library is loaded.

This method is intended to be used by GUI editors.

Parameters:

editor - the new IlvPrototypeLibraryEditor object to be registered.

See Also:

IlvPrototypeLibraryEditor

getURL

public URL getURL()

Returns the location from which the library was loaded.

setURL

public void setURL(URL url)

Sets the location from which the library was loaded.

getAllLibraries

public static Enumeration getAllLibraries()

Returns all the prototype libraries currently loaded or created.

Returns:

an enumeration of IlvPrototypeLibrary objects.

getPrototype

public static IlvPrototype getPrototype(String prototypeURL,
                                        Class jarClass)
                                 throws MalformedURLException,
                                        IlvReadFileException,
                                        IOException

Reads a prototype from a URL, or from a JAR archive.

The URL is of the form http://host/dir/library.ivl#proto, where library.ivl is the name of the prototype library file, and proto is the name of the prototype. If the prototype name is omitted, the first prototype of the library is returned. If the URL is a relative URL with a protocol of "file" and if jarClass is not null, the method tries to find the library in the JAR archive from which the class was loaded.

If the prototype library has already been loaded, it is not reloaded.

Parameters:

prototypeURL - A URL of the form http://host/dir/library.ivl#proto.

jarClass - The class used to find the library in a JAR.

Throws:

MalformedURLException - if the URL is not correct.

IlvReadFileException - if the library file is not correctly formatted, or if the library or the prototype is not found.

IOException - on input errors.

Since:

JViews 3.5