ilog.views.symbology.palettes

Class IlvPaletteManager

java.lang.Object

ilog.views.symbology.palettes.IlvPaletteManager

public class IlvPaletteManager
extends Object

This object manage a set of palettes. There are two scenarios how to use palettes:

• Palettes on the class path (without palette manager).
• Palettes dynamically loaded from URLs (with palette manager).

A palette can be stored in a jar file. If this jar file is added to the class path, a diagrammer is able to load the palette, but it is not able to modify a palette. In this case, no palette manager is necessary. This is suitable for an application with the following characteristic:

• The number of palettes used by the application is fixed.
• All palettes that occur in the application are known in advance, before the application starts (hence they can be added to the class path).
• The palettes are not modified while the application runs.

Applets that use palettes must have the palette jars on the class path. If applets need to modify palettes, they need certain security permissions (modifying palettes requires manipulating class loaders). See load(URL) for details.

A palette manager is used when the application must be able to load palettes dynamically from the file system or from an URL. It must also be used if the palettes are not static, i.e., if the application modifies the palette at run time. In order to enable SDM to use the palettes currently contained in the palette manager, the palette manager must be attached to the diagrammer (see attach(IlvCSSCompatible). When the palette manager is no longer used, the palette manager should be detached (see detach(ilog.views.util.cssbeans.IlvCSSCompatible)) in order to clean up the memory. This is suitable for an application if one of the following requirements holds:

• The user of the application can decide at runtime which palette should be used.
• The application must be able to load a palette from any URL.
• The application allows to modify the palette and to store it to a file.

In all these cases, a palette manager must be allocated and must be attached to the diagrammer (or its SDM engine).

Saving palettes into jars works like this: The palette is first stored in a working directory (see setWorkingDirectory(java.io.File)) and then put into a jar. Hence, applications that want to save palettes into jars must provide a working directory.

Here is some example code how to use a palette manager:

 IlvPaletteManager paletteManager = new IlvPaletteManager();
 paletteManager.attach(diagrammer);
 paletteManager.setWorkingDirectory(fileOfWorkingDirectory);

 // load palettes from a jar (the jar might contain many palettes)
 IlvPalette[] palettes = paletteManager.load(paletteJarURL);
 ...
 // save one palette into a jar
 paletteManager.save(myPalette, paletteJarURL);
 ...
 // later, if the palette manager is no longer used:
 paletteManager.detach();
 

Since:

JViews 8.0

Constructor Summary

Constructors

Constructor and Description
IlvPaletteManager() Creates an empty palette manager.
IlvPaletteManager(ilog.views.util.cssbeans.IlvCSSCompatible target) Creates an empty palette manager for the input target.

Method Summary

Modifier and Type	Method and Description
void	add(IlvPalette palette) Adds a palette.
void	addPaletteManagerListener(PaletteManagerListener l) Adds a listener that listens to palette manager events.
void	attach(ilog.views.util.cssbeans.IlvCSSCompatible target) Attaches the palette manager to a diagrammer or an SDM engine.
boolean	contains(IlvPalette palette) Returns whether the palette is contained in this manager.
void	detach() Detaches all diagrammers or SDM engines currently attached.
void	detach(ilog.views.util.cssbeans.IlvCSSCompatible target) Detaches the diagrammer or SDM engine.
protected void	firePaletteAdded(IlvPalette palette) Fires a event when adding a palette to the palette manager.
protected void	firePaletteRemoved(IlvPalette palette) Fires a event when removing a palette from the palette manager.
ilog.views.util.cssbeans.IlvCSSCompatible[]	getAttachComponents() Returns the components the palette manager is attached to.
ClassLoader	getClassLoader() Returns the class loader used by this palette manager.
IlvPalette	getPalette(int index) Returns the palette at specified index.
IlvPalette	getPalette(String paletteResourceName) Returns the palette that has the given palette resource name.
int	getPaletteCount() Returns the number of palettes.
int	getPaletteIndex(IlvPalette palette) Returns the index of a palette.
ArrayList	getPalettesToUpdate(String resourceName) Returns a list of palettes containing symbols referencing the given resource name as subsymbol
IlvPalette	getPaletteWithSymbol(String symbolFullID, String symbolCSSResourceName, String symbolClassName) Returns the palette that contains a symbol that matches the input parameters.
File	getWorkingDirectory() Returns the working directory in which palettes are saved before being packaged as jar files
boolean	isAttached(ilog.views.util.cssbeans.IlvCSSCompatible target) Returns true if the input target is attached to this palette manager.
boolean	isPaletteReadOnly(IlvPalette palette) Indicates if the specified palette is locked in read-only mode.
IlvPalette	load(String palettePackageName) Loads a palette and adds it to the palette manager.
IlvPalette[]	load(URL paletteJarURL) This method loads the content of jar file containing one or several palette definitions.
void	remove(IlvPalette palette) Removes the palette from the palette manager.
void	removeAll() Removes all palettes.
void	removePaletteManagerListener(PaletteManagerListener l) Removes a listener that listens to palette manager events.
void	save(IlvPalette palette, File jar) Save the specified palette in the working directory and package it into a jar file referenced by given URL The palette must belong to this palette manager.
void	save(IlvPalette palette, File jar, boolean cleanBefore, boolean cleanAfter) Save the specified palette in the working directory and package it into a jar file referenced by given URL The palette must belong to this palette manager.
void	setAndCreateWorkingDirectory(File parent, String directory) This method is for convenience.
void	setWorkingDirectory(File workingDirectory) Sets the working directory in which palettes are saved before being packaged as jar files.
void	updateSymbolReferences(ArrayList palettesToUpdate, String resourceName, String oldName, String newName) Update reference to a subsymbol with a new resource name, in a list of palettes.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvPaletteManager

public IlvPaletteManager()

Creates an empty palette manager.

IlvPaletteManager

public IlvPaletteManager(ilog.views.util.cssbeans.IlvCSSCompatible target)

Creates an empty palette manager for the input target. It attaches the manager to the target,

See Also:

attach(ilog.views.util.cssbeans.IlvCSSCompatible)

Method Detail

attach

public void attach(ilog.views.util.cssbeans.IlvCSSCompatible target)

Attaches the palette manager to a diagrammer or an SDM engine. If the palette manager is not attached, SDM is not able to use the palettes contained in the manager when executing the CSS, unless the palettes are added to the class path of your application. If the palette manager is attached to a diagrammer, this diagrammer can use all palettes contained in the palette manager no matter whether they are in the class path or not.

It is possible to attach the palette manager to multiple targets at the same time. When the palette manager is not anymore needed for a specific target, call detach(IlvCSSCompatible). If the palette manager is not anymore needed for any target, call detach(). It cleans up the memory of the palette manager.

If you attach the palette manager to a diagrammer, it is not necessary to attach it as well to the SDM engine contained in the diagrammer, since this is already handled automatically.

Parameters:

target - Either an IlvDiagrammer or an IlvSDMEngine.

See Also:

detach(), getAttachComponents()

detach

public void detach(ilog.views.util.cssbeans.IlvCSSCompatible target)

Detaches the diagrammer or SDM engine. This must be called when the palette manager is no longer needed for the input target. It cleans up the memory.

Parameters:

target - Either an IlvDiagrammer or an IlvSDMEngine that was previously attached to the manager.

See Also:

attach(ilog.views.util.cssbeans.IlvCSSCompatible)

detach

public void detach()

Detaches all diagrammers or SDM engines currently attached. This must be called when the palette manager is no longer needed. It cleans up the memory.

See Also:

attach(ilog.views.util.cssbeans.IlvCSSCompatible)

getAttachComponents

public ilog.views.util.cssbeans.IlvCSSCompatible[] getAttachComponents()

Returns the components the palette manager is attached to.

Returns:

Either an IlvDiagrammer or an IlvSDMEngine.

See Also:

attach(ilog.views.util.cssbeans.IlvCSSCompatible)

isAttached

public boolean isAttached(ilog.views.util.cssbeans.IlvCSSCompatible target)

Returns true if the input target is attached to this palette manager.

See Also:

attach(ilog.views.util.cssbeans.IlvCSSCompatible)

getClassLoader

public ClassLoader getClassLoader()

Returns the class loader used by this palette manager. This may return null if the allocation of the special class loader for palettes was not successful. This happens usually only in applets that don't have the permission to manipulate class loaders.

add

public void add(IlvPalette palette)

Adds a palette. An PaletteManagerEvent is fired through the paletteAdded(PaletteManagerEvent evt) method of PaletteListener class.

If is not possible to add the same IlvPalette object to two different palette managers. You must first remove it from one palette manager before adding it to another palette manager.

Parameters:

palette - The palette to add.

remove

public void remove(IlvPalette palette)

Removes the palette from the palette manager. An PaletteManagerEvent is fired through the paletteRemoved(PaletteManagerEvent evt) method of PaletteListener class.

Parameters:

palette - The palette to remove.

removeAll

public void removeAll()

Removes all palettes.

getPalette

public IlvPalette getPalette(String paletteResourceName)

Returns the palette that has the given palette resource name.

Parameters:

paletteResourceName - The palette resource name to search for

Returns:

The palette

See Also:

IlvPalette.getPaletteResourceName()

getPalette

public IlvPalette getPalette(int index)

Returns the palette at specified index.

Parameters:

index - The index of the palette.

Returns:

The palette.

getPaletteCount

public int getPaletteCount()

Returns the number of palettes.

contains

public boolean contains(IlvPalette palette)

Returns whether the palette is contained in this manager.

Returns:

true if the palette has already been added in the palette manager, otherwise false

getPaletteWithSymbol

public IlvPalette getPaletteWithSymbol(String symbolFullID,
                                       String symbolCSSResourceName,
                                       String symbolClassName)

Returns the palette that contains a symbol that matches the input parameters. First, a palette containing a symbol with the full ID is searched. If none is found, a palette containing a symbol with the same access string to the symbol CSS and the symbol class name is searched. If no palette is found, it returns null.

Parameters:

symbolFullID - The full ID of the symbol. Can be null.

symbolCSSResourceName - The resource access string to the symbol CSS.

symbolClassName - The class name of the symbol.

Returns:

The palette

See Also:

IlvPaletteBaseObject.getFullID(), IlvPaletteSymbol.getCSSResourceName(), IlvPaletteSymbol.getClassName()

addPaletteManagerListener

public void addPaletteManagerListener(PaletteManagerListener l)

Adds a listener that listens to palette manager events.

removePaletteManagerListener

public void removePaletteManagerListener(PaletteManagerListener l)

Removes a listener that listens to palette manager events.

firePaletteAdded

protected void firePaletteAdded(IlvPalette palette)

Fires a event when adding a palette to the palette manager.

Parameters:

palette - The palette which has been added.

firePaletteRemoved

protected void firePaletteRemoved(IlvPalette palette)

Fires a event when removing a palette from the palette manager.

Parameters:

palette - The palette which has been removed.

getPaletteIndex

public int getPaletteIndex(IlvPalette palette)

Returns the index of a palette.

Parameters:

palette - The palette

load

public IlvPalette[] load(URL paletteJarURL)
                  throws IOException

This method loads the content of jar file containing one or several palette definitions. An IlvPalette instance is created and initialized for each palette definition, and is added in this palette manager.

This method can be used to load palettes dynamically at runtime from jar files. However, this works in applets only if the applet has the permission to manipulate files and to allocate class loaders. If you implement an applet that will not have the appropriate permissions, you should put all palettes used by the applet into the class path of the applet and load them by load(String) instead. If the palette to load has the same jar URL that one which is already loaded then it will not be loaded again and only one instance of this palette will be stored in the manager.

Parameters:

paletteJarURL - The URL of the jar file containing the palette descriptions.

Returns:

IlvPalette[] An array containing the instances of palettes which have been created and loaded. If the palette is already loaded it will be returned is this array.

Throws:

SecurityException - If this method is used in an applet that has not the permissions to allocate a class loader.

IOException

See Also:

load(String)

load

public IlvPalette load(String palettePackageName)
                throws IOException

Loads a palette and adds it to the palette manager. The input string must correspond to the package name of the palette (see IlvPalette.setPackageName(java.lang.String)), for instance dir1/dir2/.../dirN/.

This method can only be used if the palette was added to the class path of the applet or application. The palette is searched on the class path and if found, it is added to this palette manager and returned as result. If the palette is not found on the class path, null is returned.

In order to load palettes from jar files that are not on the class path, use load(URL).

Parameters:

palettePackageName - The package name of the palette.

Returns:

The loaded palette, or null if the palette cannot be loaded.

Throws:

IOException

See Also:

load(URL)

save

public void save(IlvPalette palette,
                 File jar)
          throws IOException

Save the specified palette in the working directory and package it into a jar file referenced by given URL The palette must belong to this palette manager. This method does not clean the working directory before or after saving.

Parameters:

palette - The palette to saved.

jar - The jar file.

Throws:

IOException

See Also:

setWorkingDirectory(java.io.File), save(IlvPalette,File,boolean,boolean)

save

public void save(IlvPalette palette,
                 File jar,
                 boolean cleanBefore,
                 boolean cleanAfter)
          throws IOException

Save the specified palette in the working directory and package it into a jar file referenced by given URL The palette must belong to this palette manager. If the flag cleanBefore is true, the working directory is cleaned before saving the palette. This avoids that any old files of the working directory are contained in the resulting palette. If the flag cleanAfter is true, the working directory is cleaned after saving the palette.

Parameters:

palette - The palette to saved.

jar - The jar file.

cleanBefore - Whether the working directory is cleaned before saving

cleanAfter - Whether the working directory is cleaned after saving

Throws:

IOException

See Also:

setWorkingDirectory(java.io.File)

getWorkingDirectory

public File getWorkingDirectory()

Returns the working directory in which palettes are saved before being packaged as jar files

setWorkingDirectory

public void setWorkingDirectory(File workingDirectory)

Sets the working directory in which palettes are saved before being packaged as jar files.

Parameters:

workingDirectory - the new current working directory

setAndCreateWorkingDirectory

public void setAndCreateWorkingDirectory(File parent,
                                         String directory)
                                  throws IOException

This method is for convenience. It sets the working directory relative to a parent directory. If the parent directory is null, it sets the working directory relative to the current directory (usually the directory where the application started). If the working directory does not exist, it tries to create the working directory.

Parameters:

parent - The parent directory.

directory - The path name of the working directory.

Throws:

IOException

isPaletteReadOnly

public boolean isPaletteReadOnly(IlvPalette palette)

Indicates if the specified palette is locked in read-only mode. Palettes loaded using load(String) are read-only.

Parameters:

palette - The palette

updateSymbolReferences

public void updateSymbolReferences(ArrayList palettesToUpdate,
                                   String resourceName,
                                   String oldName,
                                   String newName)

Update reference to a subsymbol with a new resource name, in a list of palettes. Palettes are saved when update is done.

Parameters:

palettesToUpdate - List of palettes to update

resourceName - Resource name to search

oldName - Name to update

newName - New name

Since:

JViews 8.1

getPalettesToUpdate

public ArrayList getPalettesToUpdate(String resourceName)

Returns a list of palettes containing symbols referencing the given resource name as subsymbol

Parameters:

resourceName - The resource name to search

Returns:

ArrayList The list of palettes.

Since:

JViews 8.1