ilog.views.sdm.util

Class IlvXMLConnector

java.lang.Object

ilog.views.sdm.util.IlvXMLConnector

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

IlvPersistentSDMModelXMLConnector, IlvXSLConnector

public class IlvXMLConnector
extends Object
implements Serializable

This class is responsible for reading and writing an SDM model from/to an XML file.

Here is an example that illustrates the format of the XML SDM files:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE SDM>
 <SDM>
   <activity id="1">
     <property name="label">Activity 1</property>
     <property name="x">291.125</property>
     <property name="y">56.375</property>
   </activity>
   <activity id="2">
     <property name="label">Activity 2</property>
     <property name="x">195.33594</property>
     <property name="y">87.375</property>
   </acivity>
   <transition id="3" islink="true" from="1" to="2" />
 </SDM>
 

If you need to read and write XML files with another format, you can subclass IlvXMLConnector and associate an instance of your subclass with an SDM engine using the method IlvSDMEngine.setXMLConnector(ilog.views.sdm.util.IlvXMLConnector).

You can also replace the XML connector class used by an SDM engine by adding a rule like the following in the style sheet:

 XMLConnector {
   class : "mypackage.MyXMLConnector";
 }
 

The main entry points to IlvXMLConnector are readXML(ilog.views.sdm.IlvSDMModel,java.io.InputStream,boolean,java.util.Hashtable), readXML(ilog.views.sdm.IlvSDMModel,java.io.Reader,boolean,java.util.Hashtable), readXML(ilog.views.sdm.IlvSDMModel,java.lang.String,boolean,java.util.Hashtable), and writeXML.

The default implementation of the readXML method uses a SAX parser to read the XML source. To modify the way the XML source is read, you can:

• Override the initXMLReader method. In your implementation, you can set your own document handler to interpret your XML format.
• Override the parse(org.xml.sax.InputSource) method. This allows you to read the XML file a completely different way, for example by loading a DOM tree.

The class IlvXMLConnector provides utility methods to create the objects read from the XML file and to set their properties. These utility methods are:

• createNode
• createLink
• addObject
• setID
• setFrom
• setTo
• setProperty

These methods ensure the consistency of the model by handling forward references and automatic reallocation of IDs. When you subclass IlvXMLConnector to read your own XML format, you should call these methods instead of calling the IlvSDMModel methods directly.

The default implementation of writeXML creates a copy of the SDM model as a DOM tree, and then writes this DOM tree to the XML output stream. To modify the output format, you can override the buildDOM method.

The XML connector can also read and write data to/from an existing DOM document, through the methods readDOM and writeDOM.

The XML connector serializes and deserializes the properties of the SDM model objects using the IlvConvert class. If a property value is not a String, it is converted to a String, and its class is saved as the type attribute of the property element in the XML file. When the XML stream is read back, the property will be converted back to the saved type. If you use object properties that have a custom type, you can register a converter from String to your custom class and the inverse using the IlvConvert.addConverter(ilog.views.util.convert.IlvConverter) method.

Since:

JViews 4.0

See Also:

IlvSDMEngine.setXMLFile(java.lang.String), IlvSDMEngine.readXML(java.io.Reader), IlvSDMEngine.readXML(java.io.InputStream), IlvSDMEngine.readXML(java.lang.String), IlvSDMEngine.writeXML(java.io.OutputStream), IlvSDMEngine.writeXML(java.io.Writer), IlvSDMEngine.readDOM(org.w3c.dom.Document), IlvSDMEngine.writeDOM(org.w3c.dom.Document), Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
int	LOOSE_FORMAT Identifies the output format in which XML elements describing the objects of the data model can have any XML tag.
int	STRICT_FORMAT Identifies the output format in which XML elements describing the nodes of the data model always have the XML tag "node", and those describing the links of the data model always have the XML tag "link".

Constructor Summary

Constructors

Constructor and Description
IlvXMLConnector() Creates a new IlvXMLConnector.

Method Summary

Modifier and Type	Method and Description
protected void	addForwardRef(Object link, String id, boolean to) This helper method implements forward references in the XML input source.
protected void	addObject(Object object, Object parent) Adds an object that has been read from the XML source or document to the SDM data model.
protected void	buildDOM(Document document, IlvSDMModel model, Enumeration objects) This method is called by writeXML to build a DOM tree that represents the specified SDM data model.
protected Object	createLink(String tag) Creates a new link in the SDM data model.
protected Object	createNode(String tag) Creates a new node in the SDM data model.
IlvSDMEngine	getEngine() Returns the calling engine.
IlvMModel	getMetadata() Returns the last metadata found.
protected IlvSDMModel	getModel() Returns the SDM data model that is currently being read or written.
int	getOutputFormat() Returns the output format of the XML files generated by this XML connector.
Object	getParent() Returns the parent object.
String	getPublicDTDId() Returns the public DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.
String	getRootElementTag() Returns the tag of the root element of the documents generated by this XML connector.
String	getSystemDTDId() Returns the system DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.
protected void	initParser(Parser parser) Deprecated. Since JViews 5.0, you should override the method initXMLReader(org.xml.sax.XMLReader) instead.
protected void	initXMLReader(XMLReader reader) This method is called by parse(org.xml.sax.InputSource) to initialize the SAX2 XML reader.
boolean	isCheckingRootElementTag() Returns true if this connector checks that the XML document's root element has the tag specified by setRootElementTag(java.lang.String).
boolean	isIncremental() Returns the flag specifying whether reading an XML file creates new objects or just sets the properties of existing objects.
boolean	isSavingDTD() Sets the flag specifying whether the XML connector saves the DTD public and system identifiers in the DOCTYPE declaration of the XML document.
boolean	isSavingPropertyTypes() Returns true if this XML connector saves the types of properties to the XML stream.
boolean	isValidating() Returns the validating state of the XML parser.
protected void	parse(Document document) Parses a DOM document.
protected void	parse(InputSource in) Parses an XML input source.
protected void	parseProcessingInstruction(String data) Parses a processing instruction whose target is "sdm".
Enumeration	readDOM(IlvSDMModel model, Document document, boolean insert, Hashtable properties) Reads an SDM model from a DOM document.
Enumeration	readXML(IlvSDMModel model, InputStream in, boolean insert, Hashtable properties) Reads an SDM model from an XML input stream.
Enumeration<?>	readXML(IlvSDMModel model, Reader reader, boolean insert, Hashtable properties) Reads an SDM model from an XML input stream.
Enumeration	readXML(IlvSDMModel model, String url, boolean insert, Hashtable properties) Reads an SDM model from an XML input URL.
protected void	resolveForwardRefs(Object node, String id) Resolves a forward reference to a source or destination node.
void	setCheckingRootElementTag(boolean check) Enables/disables the checking of the tag of the XML document's root element.
void	setEngine(IlvSDMEngine engine) Sets the calling engine.
protected void	setFrom(Object link, Object from) Sets the source of a link.
protected void	setFrom(Object link, String id) Sets the source of a link.
protected String	setID(Object obj, String id) Sets the identifier of an object.
void	setIncremental(boolean incremental) Specifies whether reading an XML file should always create new objects or just set the properties of existing objects.
void	setMetadata(IlvMModel model) Sets metadata, to be saved in the next writeXML.
void	setOutputFormat(int format) Sets the format of the XML files generated by this XML connector.
void	setParent(Object parent) Sets the parent object.
protected void	setProperty(Object object, String name, Object value) Sets a property of an object.
void	setPublicDTDId(String id) Sets the public DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.
void	setRootElementTag(String tag) Sets the tag of the root element of the documents generated by this XML connector.
void	setSavingDTD(boolean savingDTD) Sets the flag specifying whether the XML connector saves the DTD public and system identifiers in the DOCTYPE declaration of the XML document.
void	setSavingPropertyTypes(boolean savingPropertyTypes) Specifies whether the types of the properties are saved to the XML stream or not.
void	setSystemDTDId(String id) Sets the system DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.
protected void	setTo(Object link, Object to) Sets the destination of a link.
protected void	setTo(Object link, String id) Sets the destination of a link.
void	setValidating(boolean validating) Sets the XML parser to validating or nonvalidating mode.
void	writeDOM(IlvSDMModel model, Document document, Enumeration objects, Hashtable properties) Writes a set of objects from an SDM model to a DOM document.
void	writeXML(IlvSDMModel model, OutputStream out, Enumeration objects, Hashtable properties) Writes a set of objects from an SDM model to an XML output stream.
void	writeXML(IlvSDMModel model, Writer writer, Enumeration objects, Hashtable properties) Writes a set of objects from an SDM model to an XML writer.

Methods inherited from class java.lang.Object

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

Field Detail

STRICT_FORMAT

public int STRICT_FORMAT

Identifies the output format in which XML elements describing the nodes of the data model always have the XML tag "node", and those describing the links of the data model always have the XML tag "link".

See Also:

setOutputFormat(int)

LOOSE_FORMAT

public int LOOSE_FORMAT

Identifies the output format in which XML elements describing the objects of the data model can have any XML tag.

See Also:

setOutputFormat(int)

Constructor Detail

IlvXMLConnector

public IlvXMLConnector()

Creates a new IlvXMLConnector.

Method Detail

setOutputFormat

public void setOutputFormat(int format)

Sets the format of the XML files generated by this XML connector. There are two possible formats:

1. If format is STRICT_FORMAT, the nodes of the graph are always saved as XML elements of tag "node", and the links are always saved as XML elements of tag "link". The symbolic type of the objects (as returned by the IlvSDMModel.getTag(java.lang.Object) method) is saved as an attribute of name "type".
2. If format is LOOSE_FORMAT, the format is slightly different: all the objects are saved as XML elements whose tag is the SDM symbolic type returned by the IlvSDMModel.getTag(java.lang.Object) method. This format cannot generally be described using a DTD, but it is easier to read.

The IlvXMLConnector accepts both formats when it reads an XML source or document. The output format is set according to the format of the input file.

The default value is LOOSE_FORMAT.

Parameters:

format - The format of the XML files.

getOutputFormat

public int getOutputFormat()

Returns the output format of the XML files generated by this XML connector.

See Also:

setOutputFormat(int)

setSavingDTD

public void setSavingDTD(boolean savingDTD)

Sets the flag specifying whether the XML connector saves the DTD public and system identifiers in the DOCTYPE declaration of the XML document. By default, the flag is false: no DTD is saved.

Parameters:

savingDTD - If true, the writeXML method saves the DTD identifiers returned by getPublicDTDId() and getSystemDTDId() in the DOCTYPE declaration of the XML document. Otherwise, no DTD identifiers are saved (the DOCTYPE declaration contains only the tag name of the root element, returned by getRootElementTag()).

isSavingDTD

public boolean isSavingDTD()

Sets the flag specifying whether the XML connector saves the DTD public and system identifiers in the DOCTYPE declaration of the XML document.

See Also:

setSavingDTD(boolean)

setValidating

public void setValidating(boolean validating)

Sets the XML parser to validating or nonvalidating mode. By default, the XML parser is nonvalidating.

Parameters:

validating - The validating flag.

isValidating

public boolean isValidating()

Returns the validating state of the XML parser.

isSavingPropertyTypes

public boolean isSavingPropertyTypes()

Returns true if this XML connector saves the types of properties to the XML stream.

Since:

JViews 6.0

See Also:

setSavingPropertyTypes(boolean)

setSavingPropertyTypes

public void setSavingPropertyTypes(boolean savingPropertyTypes)

Specifies whether the types of the properties are saved to the XML stream or not.

If this flag is set to true, for properties whose values are not String, the class is saved to the XML stream as the type attribute of the property element. When the XML stream is read back, the property value is converted back from String to the saved type. This mechanism allows nonString properties to be saved to XML files.

By default, the flag is false, so property types are not saved.

Parameters:

savingPropertyTypes - If true, for properties whose values are not String, the class is saved to the XML stream as the type attribute of the property element. When the XML stream is read back, the value is converted back from String to the saved type. This mechanism allows for nonString properties to be saved to XML files.

Since:

JViews 6.0

setPublicDTDId

public void setPublicDTDId(String id)

Sets the public DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.

The default public DTD identifier is "-//ILOG//JViews/SDM 4.0".

Parameters:

id - The public DTD identifier.

See Also:

setSavingDTD(boolean), getPublicDTDId()

getPublicDTDId

public String getPublicDTDId()

Returns the public DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.

See Also:

setSavingDTD(boolean), setPublicDTDId(java.lang.String)

setSystemDTDId

public void setSystemDTDId(String id)

Sets the system DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.

The default system DTD identifier is "sdm.dtd".

Parameters:

id - The system DTD identifier.

See Also:

setSavingDTD(boolean), getSystemDTDId()

setRootElementTag

public void setRootElementTag(String tag)

Sets the tag of the root element of the documents generated by this XML connector.

By default, the tag is "SDM". The tag is updated when a file with a different root element tag is read.

Parameters:

tag - The root element tag.

getRootElementTag

public String getRootElementTag()

Returns the tag of the root element of the documents generated by this XML connector.

isCheckingRootElementTag

public boolean isCheckingRootElementTag()

Returns true if this connector checks that the XML document's root element has the tag specified by setRootElementTag(java.lang.String).

Since:

JViews 6.0

See Also:

setCheckingRootElementTag(boolean)

setCheckingRootElementTag

public void setCheckingRootElementTag(boolean check)

Enables/disables the checking of the tag of the XML document's root element.

If checking is enabled, the readXML(ilog.views.sdm.IlvSDMModel, java.lang.String, boolean, java.util.Hashtable) and readDOM(ilog.views.sdm.IlvSDMModel, org.w3c.dom.Document, boolean, java.util.Hashtable) methods check that the tag of the document's root element is the tag specified by setRootElementTag(java.lang.String). If the tag is not correct, an exception of type IlvNotAnSDMDocumentException is thrown.

Note:: The tag "SDM" is always accepted, even if another tag was specified through setRootElementTag(java.lang.String).

Parameters:

check - If true, the connector will check when reading an XML stream that the root element has the tag specified by setRootElementTag(java.lang.String). If the element tag is wrong, the readXML(ilog.views.sdm.IlvSDMModel, java.lang.String, boolean, java.util.Hashtable) method and its variants will throw an IlvNotAnSDMDocumentException.

Since:

JViews 6.0

getSystemDTDId

public String getSystemDTDId()

Returns the system DTD identifier saved in the DOCTYPE declaration if isSavingDTD() returns true.

See Also:

setSavingDTD(boolean), setSystemDTDId(java.lang.String)

setIncremental

public void setIncremental(boolean incremental)

Specifies whether reading an XML file should always create new objects or just set the properties of existing objects.

Parameters:

incremental - If this parameter is false, every XML element read from the input source will cause a new object to be created and added to the SDM model. If this parameter is true, the XML connector looks for an existing object with the same identifier. If the object already exists in the SDM model, no new object is created: its properties are simply updated according to the contents of the XML source.

Since:

JViews 5.5

isIncremental

public boolean isIncremental()

Returns the flag specifying whether reading an XML file creates new objects or just sets the properties of existing objects.

Since:

JViews 5.5

setParent

public void setParent(Object parent)

Sets the parent object. The objects created by the next read operation will be children of this parent object. The parent object is reset to null after each read operation.

Parameters:

parent - The parent object.

Since:

JViews 5.5

getParent

public Object getParent()

Returns the parent object.

Since:

JViews 5.5

See Also:

setParent(java.lang.Object)

readXML

public Enumeration readXML(IlvSDMModel model,
                           String url,
                           boolean insert,
                           Hashtable properties)
                    throws IlvSDMException,
                           IOException

Reads an SDM model from an XML input URL. The model must be editable: the IlvSDMModel.isEditable() method must return true, and the editing methods (IlvSDMModel.addObject(java.lang.Object, java.lang.Object, java.lang.Object), IlvSDMModel.removeObject(java.lang.Object), and IlvSDMModel.setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object)) must be implemented.

This method calls the parse(org.xml.sax.InputSource) method that reads the XML input source using a SAX parser.

Parameters:

model - The SDM model to which the objects read from the XML file will be added.

url - The URL to read from.

insert - Must be true if the objects are read into a nonempty model.

properties - If non-null, the processing instruction <?sdm prop1="value1" prop2="value2"?> is parsed (if present), and the properties that it contains are stored in the Hashtable parameter.

Returns:

If insert is true, this method returns an enumeration of the objects read from the XML source. Otherwise, the method returns null.

Throws:

IlvNotAnSDMDocumentException - if the root element of the XML document does not have the tag specified by setRootElementTag(java.lang.String), and if setCheckingRootElementTag(true) was called.

IlvSDMException - if the model is not editable, or if an error occurred while reading or parsing the XML file.

IOException - if an I/O error occurred.

See Also:

readXML(ilog.views.sdm.IlvSDMModel,java.io.InputStream,boolean,java.util.Hashtable), readXML(ilog.views.sdm.IlvSDMModel,java.io.Reader,boolean,java.util.Hashtable), readDOM(ilog.views.sdm.IlvSDMModel,org.w3c.dom.Document,boolean,java.util.Hashtable)

readXML

public Enumeration readXML(IlvSDMModel model,
                           InputStream in,
                           boolean insert,
                           Hashtable properties)
                    throws IlvSDMException,
                           IOException

Reads an SDM model from an XML input stream. The model must be editable: the IlvSDMModel.isEditable() method must return true, and the editing methods (IlvSDMModel.addObject(java.lang.Object, java.lang.Object, java.lang.Object), IlvSDMModel.removeObject(java.lang.Object), and IlvSDMModel.setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object)) must be implemented.

This method calls the parse(org.xml.sax.InputSource) method that reads the XML input source using a SAX parser.

Parameters:

model - The SDM model to which the objects read from the XML file will be added.

in - The input stream to read from.

insert - Must be true if the objects are read into a nonempty model.

properties - If non-null, the processing instruction <?sdm prop1="value1" prop2="value2"?> is parsed (if present), and the properties that it contains are stored in the Hashtable parameter.

Returns:

If insert is true, this method returns an enumeration of the objects read from the XML stream. Otherwise, the method returns null.

Throws:

IlvNotAnSDMDocumentException - if the root element of the XML document does not have the tag specified by setRootElementTag(java.lang.String), and if setCheckingRootElementTag(true) was called.

IlvSDMException - if the model is not editable, or if an error occurred while reading or parsing the XML file.

IOException - if an I/O error occurred.

See Also:

readXML(ilog.views.sdm.IlvSDMModel,java.lang.String,boolean,java.util.Hashtable), readXML(ilog.views.sdm.IlvSDMModel,java.io.Reader,boolean,java.util.Hashtable), readDOM(ilog.views.sdm.IlvSDMModel,org.w3c.dom.Document,boolean,java.util.Hashtable)

readXML

public Enumeration<?> readXML(IlvSDMModel model,
                              Reader reader,
                              boolean insert,
                              Hashtable properties)
                       throws IlvSDMException,
                              IOException

Reads an SDM model from an XML input stream. The model must be editable: the IlvSDMModel.isEditable() method must return true, and the editing methods (IlvSDMModel.addObject(java.lang.Object, java.lang.Object, java.lang.Object), IlvSDMModel.removeObject(java.lang.Object), and IlvSDMModel.setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object)) must be implemented.

This method calls the parse(org.xml.sax.InputSource) method that reads the XML input source using a SAX parser.

Parameters:

model - The SDM model to which the objects read from the XML file will be added.

reader - The reader to read from.

insert - Must be true if the objects are read into a nonempty model.

properties - If non-null, the processing instruction <?sdm prop1="value1" prop2="value2"?> is parsed (if present), and the properties that it contains are stored in the Hashtable parameter.

Returns:

If insert is true, this method returns an enumeration of the objects read from the XML stream. Otherwise, the method returns null.

Throws:

IlvNotAnSDMDocumentException - if the root element of the XML document does not have the tag specified by setRootElementTag(java.lang.String), and if setCheckingRootElementTag(true) was called.

IlvSDMException - if the model is not editable, or if an error occurred while reading or parsing the XML file.

IOException - if an I/O error occurred.

Since:

JViews 6.0

See Also:

readXML(ilog.views.sdm.IlvSDMModel,java.lang.String,boolean,java.util.Hashtable), readXML(ilog.views.sdm.IlvSDMModel,java.io.InputStream,boolean,java.util.Hashtable), readDOM(ilog.views.sdm.IlvSDMModel,org.w3c.dom.Document,boolean,java.util.Hashtable)

readDOM

public Enumeration readDOM(IlvSDMModel model,
                           Document document,
                           boolean insert,
                           Hashtable properties)
                    throws IlvSDMException,
                           IOException

Reads an SDM model from a DOM document. The model must be editable: the IlvSDMModel.isEditable() method must return true, and the editing methods (IlvSDMModel.addObject(java.lang.Object, java.lang.Object, java.lang.Object), IlvSDMModel.removeObject(java.lang.Object), and IlvSDMModel.setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object)) must be implemented.

This method calls the parse(org.w3c.dom.Document) method that builds the SDM model from a DOM document.

Parameters:

model - The SDM model in which the objects read from the XML file will be added.

document - The DOM document from which the SDM model will be built.

insert - Must be true if the objects are read into a non-empty model.

properties - If non-null, the processing instruction <?sdm prop1="value1" prop2="value2"?> is parsed (if present), and the properties that it contains are stored in this Hashtable parameter.

Returns:

If insert is true, this method returns an enumeration of the objects read from the XML source. Otherwise, the method returns null.

Throws:

IlvNotAnSDMDocumentException - if the root element of the XML document does not have the tag specified by setRootElementTag(java.lang.String), and if setCheckingRootElementTag(true) was called.

IlvSDMException - if the model is not editable, or if an error occurred while reading or parsing the XML file.

IOException - if an I/O error occurred.

See Also:

readXML(ilog.views.sdm.IlvSDMModel,java.io.InputStream,boolean,java.util.Hashtable)

getMetadata

public IlvMModel getMetadata()

Returns the last metadata found. A new model is returned each time a new XML file is loaded.

Returns:

Metadata, or null if no metadata was present in the last XML file.

Since:

JViews 5.5

setMetadata

public void setMetadata(IlvMModel model)

Sets metadata, to be saved in the next writeXML.

Since:

JViews 5.5

getModel

protected IlvSDMModel getModel()

Returns the SDM data model that is currently being read or written.

This method can be used to query information from the data model while implementing a subclass of IlvXMLConnector.

Note that, while reading an XML file, you should not call directly the methods of the data model to modify it. Instead, you should call the following methods of IlvXMLConnector, which ensure the consistency of the model: createNode, createLink, addObject, setID, setFrom, setTo, and setProperty.

setEngine

public void setEngine(IlvSDMEngine engine)

Sets the calling engine. The engine will be used to manage metadata while reading a document, because a metadata model may be prepended to the SDM engine.

Parameters:

engine - The calling engine.

Since:

JViews 5.5

getEngine

public IlvSDMEngine getEngine()

Returns the calling engine.

Since:

JViews 5.5

See Also:

setEngine(ilog.views.sdm.IlvSDMEngine)

createNode

protected Object createNode(String tag)

Creates a new node in the SDM data model.

Parameters:

tag - The tag of the new node.

createLink

protected Object createLink(String tag)

Creates a new link in the SDM data model.

Parameters:

tag - The tag of the new link.

addObject

protected void addObject(Object object,
                         Object parent)

Adds an object that has been read from the XML source or document to the SDM data model.

Parameters:

object - The object to add.

parent - The parent of the object (can be null).

setID

protected String setID(Object obj,
                       String id)

Sets the identifier of an object. This method handles forward references and reallocation of already-used identifiers.

Parameters:

obj - The data object whose identifier must be set.

id - The new ID read from the XML source.

Returns:

The actual identifier of the object, which can be different from the id parameter if this identifier was already used.

setFrom

protected void setFrom(Object link,
                       Object from)

Sets the source of a link.

Parameters:

link - The link object.

from - The source node.

setTo

protected void setTo(Object link,
                     Object to)

Sets the destination of a link.

Parameters:

link - The link object.

to - The destination node.

setFrom

protected void setFrom(Object link,
                       String id)

Sets the source of a link. The identifier of the source node is looked up. If the node has not yet been read, a forward reference is recorded. This method handles automatic reallocation of already-used identifiers.

Parameters:

link - The link object.

id - The identifier of the source node.

setTo

protected void setTo(Object link,
                     String id)

Sets the destination of a link. The identifier of the destination node is looked up. If the node has not yet been read, a forward reference is recorded. This method handles automatic reallocation of already-used identifiers.

Parameters:

link - The link object.

id - The identifier of the destination node.

setProperty

protected void setProperty(Object object,
                           String name,
                           Object value)

Sets a property of an object.

Note: This method is used at read time to set the model objects properties. Override it if you need to make additional computations linking property values with external data.

Parameters:

object - The data object.

name - The property name.

value - The property value.

Since:

JViews 8.5

parse

protected void parse(InputSource in)
              throws IlvSDMException,
                     IOException

Parses an XML input source. This method interprets the contents of the XML source and adds the resulting data objects to the SDM data model passed to readXML.

This method creates a SAX parser and calls initXMLReader to initialize the content handler.

Parameters:

in - The input source to parse.

Throws:

IlvSDMException

IOException

initParser

@Deprecated
protected void initParser(Parser parser)

Deprecated. Since JViews 5.0, you should override the method initXMLReader(org.xml.sax.XMLReader) instead.

This method is called by parse(org.xml.sax.InputSource) to initialize the SAX parser.

This method is still present for compatibility reasons in JViews 5.0, but you should override the new method initXMLReader(org.xml.sax.XMLReader) instead.

Parameters:

parser - The SAX1 parser.

initXMLReader

protected void initXMLReader(XMLReader reader)

This method is called by parse(org.xml.sax.InputSource) to initialize the SAX2 XML reader. The default implementation sets the parser's content handler to a default handler that interprets the XML format described in the class description. You can override this method to provide your own content handler if you want to accept a different XML format.

Parameters:

reader - The SAX2 XML reader.

Since:

JViews 5.0

addForwardRef

protected void addForwardRef(Object link,
                             String id,
                             boolean to)

This helper method implements forward references in the XML input source. You can call this method if the XML source contains a link whose source or destination node has not yet been read. The forward reference must be resolved later by calling the method resolveForwardRefs(java.lang.Object, java.lang.String).

Parameters:

link - The link whose source or destination node has not yet been read.

id - The identifier of the source or destination node.

to - false if the id specifies the source node of the link, or true if it specifies the destination node.

resolveForwardRefs

protected void resolveForwardRefs(Object node,
                                  String id)

Resolves a forward reference to a source or destination node. This method must be called every time a node with a known ID has been read, to resolve the possible forward references to this node.

Parameters:

node - The node that has just been read.

id - The identifier of the node.

parse

protected void parse(Document document)
              throws IlvSDMException

Parses a DOM document. This method traverses the document and adds the resulting data objects to the SDM data model passed to readDOM.

Parameters:

document - The document to parse.

Throws:

IlvSDMException

writeXML

public void writeXML(IlvSDMModel model,
                     OutputStream out,
                     Enumeration objects,
                     Hashtable properties)
              throws IOException

Writes a set of objects from an SDM model to an XML output stream.

This method calls buildDOM to create a copy of the SDM data model as a DOM tree, and then the DOM tree is saved to the output stream.

Parameters:

model - The SDM model that will be written to the XML stream.

out - The output stream to write to.

objects - An enumeration returning the objects to save. If null, all the objects of the model are saved.

properties - If non-null, the properties contained in this Hashtable are saved in the XML output as a processing instruction of the form <?sdm prop1="value1" prop2="value2"?>.

Throws:

IOException - if an I/O error occurred.

See Also:

writeDOM(ilog.views.sdm.IlvSDMModel,org.w3c.dom.Document,java.util.Enumeration,java.util.Hashtable), writeXML(ilog.views.sdm.IlvSDMModel,java.io.Writer,java.util.Enumeration,java.util.Hashtable)

writeXML

public void writeXML(IlvSDMModel model,
                     Writer writer,
                     Enumeration objects,
                     Hashtable properties)
              throws IOException

Writes a set of objects from an SDM model to an XML writer.

This method calls buildDOM to create a copy of the SDM data model as a DOM tree, and then the DOM tree is saved to the output stream.

Parameters:

model - The SDM model that will be written to the XML writer.

writer - The Writer to write to.

objects - An enumeration returning the objects to save. If null, all the objects of the model are saved.

properties - If non-null, the properties contained in this Hashtable are saved in the XML output as a processing instruction of the form <?sdm prop1="value1" prop2="value2"?>.

Throws:

IOException - if an I/O error occurred.

Since:

JViews 6.0

See Also:

writeDOM(ilog.views.sdm.IlvSDMModel,org.w3c.dom.Document,java.util.Enumeration,java.util.Hashtable), writeXML(ilog.views.sdm.IlvSDMModel,java.io.OutputStream,java.util.Enumeration,java.util.Hashtable)

writeDOM

public void writeDOM(IlvSDMModel model,
                     Document document,
                     Enumeration objects,
                     Hashtable properties)

Writes a set of objects from an SDM model to a DOM document.

This method calls buildDOM to create a copy of the SDM data model in the specified DOM document.

Parameters:

model - The SDM model that will be written to the XML stream.

document - The DOM document to fill with the SDM data.

objects - An enumeration returning the objects to save. If null, all the objects of the model are saved.

properties - If non-null, the properties contained in this Hashtable are saved in the XML output as a processing instruction of the form <?sdm prop1="value1" prop2="value2"?>.

See Also:

writeXML(ilog.views.sdm.IlvSDMModel,java.io.OutputStream,java.util.Enumeration,java.util.Hashtable), writeXML(ilog.views.sdm.IlvSDMModel,java.io.Writer,java.util.Enumeration,java.util.Hashtable)

buildDOM

protected void buildDOM(Document document,
                        IlvSDMModel model,
                        Enumeration objects)

This method is called by writeXML to build a DOM tree that represents the specified SDM data model.

The default implementation builds a DOM tree with the structure described in the class description. You can override this method to save the data model in a different format.

Parameters:

document - The DOM document in which the DOM tree must be built. The document is initially empty: you must create and add the root element yourself.

model - The SDM data model that is being saved.

objects - The objects of the data model that must be saved.

See Also:

setSavingDTD(boolean), setPublicDTDId(java.lang.String), setSystemDTDId(java.lang.String)

parseProcessingInstruction

protected void parseProcessingInstruction(String data)

Parses a processing instruction whose target is "sdm". The data of the processing instruction is assumed to be of the form <?sdm prop1="value1" prop2="value2"?>. This method fills the Hashtable passed as the properties parameter of the readXML method with the key/value pairs (prop1/value1, prop2/value2, ...) contained in the processing instruction.

The instruction incremental="true" is handled directly by the XML connector, and is equivalent to calling setIncremental(boolean). When the XML connector reads an XML file containing the processing instruction:

 <?sdm incremental="true"?>
 

it will read the file in incremental mode, and restore the original mode when the file has been parsed.

Parameters:

data - The data string of the processing instruction.