ilog.views.appframe.settings
Class IlvSettings

java.lang.Object
  ilog.views.appframe.settings.IlvSettings

All Implemented Interfaces:

Document, Node

Direct Known Subclasses:

IlvBeanSettings, IlvSettingsManager, IlvXMLSettings

public class IlvSettings
extends Object
implements Document

Settings are hierarchical data for configuring all kinds of objects.
They also transparently track the modifications made by the objects to their initial settings values. Modifications are saved in the user settings and restored in the next session of the application for the same user profile.
Settings are used for initializing Application Framework components, such as an IlvMenuBar. They also provide an API for initializing user objects.

Settings model
Data accessed by the settings is specified in an IlvSettingsModel that is instantiated with the createModel(short) method. Settings classes are provided for initializing the settings from different types of settings model:

• The IlvXMLSettings class initializes the settings from XML streams.
• The IlvBeanSettings class initializes the settings from bean properties.

Settings query
Objects accessed by settings are selected using query methods:

• selectElement(java.lang.String, java.lang.String, java.lang.Object)
• selectElement(ilog.views.appframe.settings.IlvSettingsQuery)
• select(ilog.views.appframe.settings.IlvSettingsQuery)
• select(java.lang.String, ilog.views.appframe.settings.IlvSettingsElement[])
• select(ilog.views.appframe.settings.IlvSettingsQuery, ilog.views.appframe.settings.IlvSettingsElement[])

See IlvSettingsQuery for more information on how to construct a query.

Result elements
Objects of the settings model selected by those queries are not directly accessible to the user. Instead, IlvSettingsNode instances are returned. Settings nodes can be either IlvSettingsAttribute or IlvSettingsElement instances.

They facilitate the manipulation of the objects of the model in many ways.
First, they cascade those objects transparently. If the settings are a settings manager, objects of the model can be selected in several settings with the same query. The settings element cascades the attributes of those objects and gives access to them as only one node.
Secondly, they return typed values to the user, such as IlvSettingsElement.getInt(java.lang.String) or IlvSettingsElement.getFont(java.lang.String), which ease the initialization of user objects initialized from the settings.

Customized settings
You can initialize your settings from other sources by defining your own IlvSettingsModel or IlvMutableSettingsModel implementation. This settings model can be set to an IlvSettings. Its data is accessible with all the query methods of the IlvSettings class returning the same resulting settings nodes,

Nested Class Summary

static class	IlvSettings.AttributeID Defines ID values that contain the value and the name of an attribute.
static class	IlvSettings.IDAttributeMapper Maps the ID value of a settings element with the value of a specified attribute.
static interface	IlvSettings.IDResolver Provides ID values for objects of the settings models.

Field Summary

static short	APPLY_DIFF_MODE Cascading constant used when settings are merged with other settings within a settings manager.
static String	EVERY_NODE_KEY Key to be used in a query to specify that all the nodes that the axis of the query applies to must be selected.
static short	READABLE Access right constant used to specify that the settings elements can be read.
static short	SET_MODE Cascading constant used when settings are merged with other settings within a settings manager.
static short	UNREADABLE Access right constant used to specify that the settings elements can neither be read nor modified.
static boolean	VERBOSE Static variable that specifies whether verbose strings depending on the Settings API should be printed on the System.out output.
static short	WRITABLE Access right constant used to specify that the settings elements can be modified.

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Constructor Summary

IlvSettings()
Constructs a new empty IlvSettings, without associated model and without name.

IlvSettings(String name)
Constructs a new IlvSettings with the specified name.

IlvSettings(String name, IlvSettingsModel model)
Constructs settings with the specified name and model.

Method Summary

void	addIDResolver(IlvSettings.IDResolver resolver) Adds the specified ID resolver for providing ID attributes for new settings types.
void	addSettingsElement(IlvSettingsElement parentElement, IlvSettingsElement element, int index) Adds the specified element to the specified parent.
Node	adoptNode(Node source)
Node	appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
boolean	areSettingsInitialized() Determines whether those settings are initialized.
boolean	canWrite() Determines whether those settings can be modified by checking if the value returned by the method getAccessRights() contains the tag value WRITABLE.
Node	cloneNode(boolean deep) Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes.
void	commit() Commits the changes made on the model associated with those settings.
short	compareDocumentPosition(Node other)
Attr	createAttribute(String name) Creates an Attr of the given name.
Attr	createAttributeNS(String namespaceURI, String qualifiedName) Creates an attribute of the given qualified name and namespace URI.
CDATASection	createCDATASection(String data) Creates a CDATASection node whose value is the specified string.
Comment	createComment(String data) Creates a Comment node given the specified string.
DocumentFragment	createDocumentFragment() Creates an empty DocumentFragment object.
Element	createElement(String tagName) Creates an element of the type specified.
Element	createElementNS(String namespaceURI, String qualifiedName) Creates an element of the given qualified name and namespace URI.
EntityReference	createEntityReference(String name) Creates an EntityReference object.
protected IlvSettingsModel	createModel(short accessRights) Creates the model of those settings.
ProcessingInstruction	createProcessingInstruction(String target, String data) Creates a ProcessingInstruction node given the specified name and data strings.
IlvSettingsElement	createSettingsElement(String type) Creates a new element with the specified type.
Text	createTextNode(String data) Creates a Text node given the specified string.
Object	ensureCorrespondingElement(IlvSettingsElement element) Ensures that the specified settings element has a cascaded element in these settings.
IlvSettingsElement	ensureSettingsElement(IlvSettingsQuery query) Ensures that a settings element of those settings is selectable from the specified query.
IlvSettingsElement	ensureSettingsElement(String type) Ensures that a root settings element with the specified type exists in those settings.
short	getAccessRights() Returns the access rights for reading and modifying the model associated with those settings.
IlvApplication	getApplication() Returns the application of those settings.
NamedNodeMap	getAttributes() Returns null as a document has no attributes.
String	getBaseURI()
short	getCascadingMode() Specifies how the content of those settings should be merged with other settings if those settings are inserted into an IlvSettingsManager manager.
NodeList	getChildNodes() A NodeList that contains all children of this node.
DocumentType	getDoctype() The Document Type Declaration (see DocumentType) associated with this document.
Element	getDocumentElement() This is a convenience attribute that allows direct access to the child node that is the root element of the document.
String	getDocumentURI()
DOMConfiguration	getDomConfig()
Element	getElementById(String elementId) Returns the Element whose ID is given by elementId.
NodeList	getElementsByTagName(String tagname) Returns a NodeList of all the Elements with a given tag name in the order in which they are encountered in a preorder traversal of the Document tree.
NodeList	getElementsByTagNameNS(String namespaceURI, String localName) Returns a NodeList of all the Elements with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of the Document tree.
Object	getFeature(String feature, String version)
Node	getFirstChild() The first child of this node.
Object	getID(Object element) Returns the ID value for the specified settings element owned by those settings.
protected Object	getID(Object element, String type, IlvSettingsModel model) Returns the ID value that uniquely identifies the specified object of the model among other objects with the same type and parent.
DOMImplementation	getImplementation() The DOMImplementation object that handles this document.
String	getInputEncoding()
Node	getLastChild() The last child of this node.
String	getLocalName() Returns the local part of the qualified name of this node.
IlvSettingsModel	getModel() Returns the model of those settings.
IlvMutableSettingsModel	getMutableModel() Returns the mutable model associated with this model.
String	getName() Returns the name of those settings.
String	getNamespaceURI() Implementation of the method Node.getNamespaceURI() method.
Node	getNextSibling() The node immediately following this node.
String	getNodeName() The name of this node.
short	getNodeType() A code representing the type of this node.
String	getNodeValue() null as this node is a document and has not associated value.
Document	getOwnerDocument() The Document object associated with this node.
Node	getParentNode() The parent of this node.
String	getPrefix() Implementation of the method Node.getPrefix() method.
Node	getPreviousSibling() The node immediately preceding this node.
IlvSettingsManager	getSettingsManager() Returns the settings manager that owns those settings.
boolean	getStrictErrorChecking()
String	getTextContent()
Object	getUserData(String key)
String	getXmlEncoding()
boolean	getXmlStandalone()
String	getXmlVersion()
boolean	hasAttributes() Returns whether this node (if it is an element) has any attributes.
boolean	hasChildNodes() Returns whether this node has any children.
Node	importNode(Node importedNode, boolean deep) Imports a node from another document to this document.
boolean	initializeSettings() Initializes the settings.
Node	insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
boolean	isDefaultNamespace(String namespaceURI)
boolean	isEqualNode(Node arg)
static boolean	IsEveryNodeKey(String key) Determines whether the specified key selects all the nodes if used in a query.
boolean	isSameNode(Node other)
boolean	isSupported(String feature, String version) Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
String	lookupNamespaceURI(String prefix)
String	lookupPrefix(String namespaceURI)
void	normalize() Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes.
void	normalizeDocument()
boolean	removeAllSettingsElements(IlvSettingsElement parent, String type) Removes all the settings elements that are children of the specified parent element and have the specified type.
Node	removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
boolean	removeIDResolver(IlvSettings.IDResolver resolver) Removes the specified ID resolver from the list of mappers stored in those settings.
boolean	removeSettingsElement(IlvSettingsElement element) Removes the model element of the settings referenced by the specified settings element.
Node	renameNode(Node n, String namespaceURI, String qualifiedName)
Node	replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
IlvSettingsElement[]	select(IlvSettingsQuery query) Returns the settings elements selected by the specified query.
IlvSettingsElement[]	select(IlvSettingsQuery query, IlvSettingsElement[] contextElements) Returns the settings elements selected by the specified query from the specified settings element.
IlvSettingsElement[]	select(String type, IlvSettingsElement[] contextElements) Returns the settings elements with the specified settings type and children of the specified contextElements.
IlvSettingsElement	selectElement(IlvSettingsQuery query) Returns the first settings element selected by the specified query.
IlvSettingsElement	selectElement(String type) Returns the first root settings element with the specified type.
IlvSettingsElement	selectElement(String type, String attributeName, Object attributeValue) Returns the first root settings element selected by the specified query parameters.
IlvSettingsNode[]	selectNodes(IlvSettingsQuery query) Returns the settings nodes selected by the specified query.
void	setAccessRights(short accessRights) Sets the rights for accessing the model associated with those settings.
void	setApplication(IlvApplication application) Sets the application that owns those settings.
void	setCascadingMode(short mode) Sets the cascading mode of those settings with other settings.
void	setDocumentURI(String documentURI)
protected boolean	setID(Object element, Object id, String type, IlvMutableSettingsModel model) Sets the specified ID value to the specified object of the model.
void	setModel(IlvSettingsModel model) Sets the model of those settings.
void	setName(String name) Sets the name of those settings.
void	setNodeValue(String nodeValue) Sets a value to this node.
void	setPrefix(String prefix) This method has no effects as documents do not support prefixes.
void	setSettingsManager(IlvSettingsManager manager) Sets the settings manager that owns those settings.
void	setStrictErrorChecking(boolean strictErrorChecking)
void	setTextContent(String textContent)
Object	setUserData(String key, Object data, UserDataHandler handler)
void	setXmlStandalone(boolean xmlStandalone)
void	setXmlVersion(String xmlVersion)

Methods inherited from class java.lang.Object

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

Field Detail

WRITABLE

public static final short WRITABLE

Access right constant used to specify that the settings elements can be modified.

See Also:

Constant Field Values

READABLE

public static final short READABLE

Access right constant used to specify that the settings elements can be read.

See Also:

Constant Field Values

UNREADABLE

public static final short UNREADABLE

Access right constant used to specify that the settings elements can neither be read nor modified.

See Also:

Constant Field Values

SET_MODE

public static final short SET_MODE

Cascading constant used when settings are merged with other settings within a settings manager.
It specifies that the nodes that are selected in those settings erase the nodes selected with the same query in settings with lower priority in the settings manager.

See Also:

getCascadingMode(), setCascadingMode(short), Constant Field Values

APPLY_DIFF_MODE

public static final short APPLY_DIFF_MODE

Cascading constant used when settings are merged with other settings within a settings manager.
It specifies that the settings it applies to represent modifications to make to settings nodes of settings of lower priority. While processing a query, settings with this mode can remove or change the attributes of nodes previously selected by settings of lower priority for the same query.

See Also:

getCascadingMode(), setCascadingMode(short), Constant Field Values

EVERY_NODE_KEY

public static String EVERY_NODE_KEY

Key to be used in a query to specify that all the nodes that the axis of the query applies to must be selected.

See Also:

IsEveryNodeKey(java.lang.String)

VERBOSE

public static boolean VERBOSE

Static variable that specifies whether verbose strings depending on the Settings API should be printed on the System.out output.

If true, verbose messages will be printed; if false, there will be no output specific to the Settings API printed. By default, the value of this variable is false.

Constructor Detail

IlvSettings

public IlvSettings()

Constructs a new empty IlvSettings, without associated model and without name.

See Also:

setName(java.lang.String), setModel(ilog.views.appframe.settings.IlvSettingsModel)

IlvSettings

public IlvSettings(String name)

Constructs a new IlvSettings with the specified name.

Parameters:

name - The name of the settings

See Also:

getName(), setModel(ilog.views.appframe.settings.IlvSettingsModel)

IlvSettings

public IlvSettings(String name,
                   IlvSettingsModel model)

Constructs settings with the specified name and model.

Parameters:

name - The name of the settings.

model - The new model of those settings.

See Also:

getName(), setModel(ilog.views.appframe.settings.IlvSettingsModel)

Method Detail

getBaseURI

public String getBaseURI()

Specified by:

getBaseURI in interface Node

compareDocumentPosition

public short compareDocumentPosition(Node other)
                              throws DOMException

Specified by:

compareDocumentPosition in interface Node

Throws:

DOMException

getTextContent

public String getTextContent()
                      throws DOMException

Specified by:

getTextContent in interface Node

Throws:

DOMException

setTextContent

public void setTextContent(String textContent)
                    throws DOMException

Specified by:

setTextContent in interface Node

Throws:

DOMException

isSameNode

public boolean isSameNode(Node other)

Specified by:

isSameNode in interface Node

lookupPrefix

public String lookupPrefix(String namespaceURI)

Specified by:

lookupPrefix in interface Node

isDefaultNamespace

public boolean isDefaultNamespace(String namespaceURI)

Specified by:

isDefaultNamespace in interface Node

lookupNamespaceURI

public String lookupNamespaceURI(String prefix)

Specified by:

lookupNamespaceURI in interface Node

isEqualNode

public boolean isEqualNode(Node arg)

Specified by:

isEqualNode in interface Node

getFeature

public Object getFeature(String feature,
                         String version)

Specified by:

getFeature in interface Node

setUserData

public Object setUserData(String key,
                          Object data,
                          UserDataHandler handler)

Specified by:

setUserData in interface Node

getUserData

public Object getUserData(String key)

Specified by:

getUserData in interface Node

getInputEncoding

public String getInputEncoding()

Specified by:

getInputEncoding in interface Document

getXmlEncoding

public String getXmlEncoding()

Specified by:

getXmlEncoding in interface Document

getXmlStandalone

public boolean getXmlStandalone()

Specified by:

getXmlStandalone in interface Document

setXmlStandalone

public void setXmlStandalone(boolean xmlStandalone)
                      throws DOMException

Specified by:

setXmlStandalone in interface Document

Throws:

DOMException

getXmlVersion

public String getXmlVersion()

Specified by:

getXmlVersion in interface Document

setXmlVersion

public void setXmlVersion(String xmlVersion)
                   throws DOMException

Specified by:

setXmlVersion in interface Document

Throws:

DOMException

getStrictErrorChecking

public boolean getStrictErrorChecking()

Specified by:

getStrictErrorChecking in interface Document

setStrictErrorChecking

public void setStrictErrorChecking(boolean strictErrorChecking)

Specified by:

setStrictErrorChecking in interface Document

getDocumentURI

public String getDocumentURI()

Specified by:

getDocumentURI in interface Document

setDocumentURI

public void setDocumentURI(String documentURI)

Specified by:

setDocumentURI in interface Document

adoptNode

public Node adoptNode(Node source)
               throws DOMException

Specified by:

adoptNode in interface Document

Throws:

DOMException

getDomConfig

public DOMConfiguration getDomConfig()

Specified by:

getDomConfig in interface Document

normalizeDocument

public void normalizeDocument()

Specified by:

normalizeDocument in interface Document

renameNode

public Node renameNode(Node n,
                       String namespaceURI,
                       String qualifiedName)
                throws DOMException

Specified by:

renameNode in interface Document

Throws:

DOMException

getName

public String getName()

Returns the name of those settings. This name uniquely identifies those settings among the settings added to an application.

Returns:

The settings name.

See Also:

setName(java.lang.String)

setName

public void setName(String name)

Sets the name of those settings.

Parameters:

name - The new name of those settings.

See Also:

getName()

initializeSettings

public boolean initializeSettings()

Initializes the settings. The default implementation is empty.

Returns:

true.

See Also:

areSettingsInitialized()

areSettingsInitialized

public boolean areSettingsInitialized()

Determines whether those settings are initialized.

Returns:

true if those settings are initialized; false otherwise.

See Also:

initializeSettings()

setModel

public void setModel(IlvSettingsModel model)

Sets the model of those settings.

Parameters:

model - The new model of those settings.

See Also:

getModel()

getModel

public IlvSettingsModel getModel()

Returns the model of those settings.

See Also:

setModel(ilog.views.appframe.settings.IlvSettingsModel)

getMutableModel

public IlvMutableSettingsModel getMutableModel()

Returns the mutable model associated with this model. If no model was specified to those settings or if the model that was set does not implement the interface IlvMutableSettingsModel, null will be returned.

Returns:

The mutable model of those settings.

getSettingsManager

public IlvSettingsManager getSettingsManager()

Returns the settings manager that owns those settings.

See Also:

setSettingsManager(ilog.views.appframe.settings.IlvSettingsManager)

setSettingsManager

public void setSettingsManager(IlvSettingsManager manager)

Sets the settings manager that owns those settings.

Parameters:

manager - The new settings manager that owns those settings.

See Also:

getSettingsManager()

setApplication

public void setApplication(IlvApplication application)

Sets the application that owns those settings.

Parameters:

application - The new application of those settings.

See Also:

getApplication()

getApplication

public IlvApplication getApplication()

Returns the application of those settings.

See Also:

setApplication(ilog.views.appframe.IlvApplication)

commit

public void commit()

Commits the changes made on the model associated with those settings. The default implementation is empty.

See Also:

getModel()

getAccessRights

public short getAccessRights()

Returns the access rights for reading and modifying the model associated with those settings. If the associated model does not implement the IlvMutableSettingsModel interface, the tag value WRITABLE is automatically removed from the returned value.
In the same way, the tag value UNREADABLE is returned if no model is associated with those settings.

Returns:

The access right value. This value is a combination of one or more of the following constants:

• UNREADABLE
• READABLE
• WRITABLE

See Also:

setAccessRights(short)

setAccessRights

public void setAccessRights(short accessRights)

Sets the rights for accessing the model associated with those settings.

Parameters:

accessRights - The new rights for accessing the model of those settings.

See Also:

getAccessRights()

canWrite

public boolean canWrite()

Determines whether those settings can be modified by checking if the value returned by the method getAccessRights() contains the tag value WRITABLE.

getID

protected Object getID(Object element,
                       String type,
                       IlvSettingsModel model)

Returns the ID value that uniquely identifies the specified object of the model among other objects with the same type and parent.
The default implementation of this method first tries to get the ID value using the ID mappers added to those settings and to the ascendant settings managers that contain those settings. ID resolvers are added to the settings using the method