ilog.views.diagrammer.datasource
Class IlvDiagrammerDataSource

java.lang.Object
  ilog.views.diagrammer.datasource.IlvDiagrammerDataSource

Direct Known Subclasses:

IlvJDBCDataSource, IlvXMLDataSource

public abstract class IlvDiagrammerDataSource
extends Object

This class defines a data source for the diagram component, IlvDiagrammer.

A data source is an object that can read and (optionally) write Diagrammer data through its read(ilog.views.diagrammer.IlvDiagrammer) and write(ilog.views.diagrammer.IlvDiagrammer) methods.

Predefined implementations of this abstract class are:

• IlvXMLDataSource, which reads and writes data from XML files
• IlvJDBCDataSource which reads data from a database through the JDBC API

Data sources can be serialized inside "project files" (see IlvDiagrammerProject). Serializing a data source must not be confused with reading/writing data represented by the data source. Serializing a data source means writing its configuration parameters to an XML configuration file. For example, a database source will have parameters like the database URL, the SQL queries, and so on. These parameters can be saved (serialized) to an XML file and reloaded (deserialized) later to re-create the data source. Data sources are serialized and deserialized through the serialize(org.w3c.dom.Element, java.net.URL) and deserialize(org.w3c.dom.Element, java.net.URL) methods.

Constructor Summary

IlvDiagrammerDataSource()

Method Summary

static IlvDiagrammerDataSource	deserialize(Element element, URL baseURL) Deserializes a data source from the specified DOM element.
protected abstract void	deserializeImpl(Element element) This method must be implemented by subclasses to read their parameters from an XML configuration file.
protected URL	getBaseURL() Returns the base URL to or from which this data source is being deserialized.
String	getDescription() Returns a description of this data source.
abstract void	read(IlvDiagrammer diagrammer) Reads data from this data source into a diagram component, IlvDiagrammer.
void	serialize(Element element, URL baseURL) Serializes this data source to the specified DOM element.
protected abstract void	serializeImpl(Element element) This method must be implemented by subclasses to save their parameters to the XML configuration file.
boolean	supportsWrite() Returns true if this data source supports writing.
abstract void	write(IlvDiagrammer diagrammer) Writes data from a diagram component, IlvDiagrammer, to this data source.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvDiagrammerDataSource

public IlvDiagrammerDataSource()

Method Detail

read

public abstract void read(IlvDiagrammer diagrammer)
                   throws IlvDiagrammerException

Reads data from this data source into a diagram component, IlvDiagrammer.

Parameters:

diagrammer - The diagram component that will display the data read from this data source.

Throws:

IlvDiagrammerException - If an exception occurs while reading data. This exception will usually contain a "cause", that is, the original low-level exception that caused the data source to fail to complete the operation.

write

public abstract void write(IlvDiagrammer diagrammer)
                    throws IlvDiagrammerException

Writes data from a diagram component, IlvDiagrammer, to this data source.

This method may have an empty implementation if the data source is read-only. Read-only data sources must return false from the supportsWrite() method.

Parameters:

diagrammer - The diagram component that contains the data to be saved to the data source.

Throws:

IlvDiagrammerException - If an exception occurs while writing data. This exception will usually contain a "cause", that is to say the original low-level exception that caused the data source to fail to complete the operation.

supportsWrite

public boolean supportsWrite()

Returns true if this data source supports writing. Read-only data sources must return false.

The default implementation returns false. This method must be overridden by subclasses that support writing.

getDescription

public String getDescription()

Returns a description of this data source. The description may be displayed by applications, for example, as the title of the frame that contains the diagram component.

This default implementation returns the URL from which the data source was deserialized.

serialize

public final void serialize(Element element,
                            URL baseURL)
                     throws IlvDiagrammerException

Serializes this data source to the specified DOM element.

Serializing a data source means saving its parameters to an XML configuration file. Serializing a data source must not be confused with requesting the data source to write the data from the diagram component.

This method sets the "class" attribute of the element to the class name of this data source and then calls serializeImpl(org.w3c.dom.Element) to let subclasses save their own configuration parameters.

Parameters:

element - The DOM element to which the data source parameters are written.

baseURL - The URL to which the configuration is being saved. This URL can be used to save URL parameters of the data source as relative URLs.

Throws:

IlvDiagrammerException - If an exception occurs while serializing the data source. This exception will usually contain a "cause", that is to say the original low-level exception that caused the operation to fail.

serializeImpl

protected abstract void serializeImpl(Element element)
                               throws IlvDiagrammerException

This method must be implemented by subclasses to save their parameters to the XML configuration file.

Parameters:

element - The DOM element to which the data source parameters are written.

Throws:

IlvDiagrammerException - If an exception occurs while serializing the data source.

deserialize

public static IlvDiagrammerDataSource deserialize(Element element,
                                                  URL baseURL)
                                           throws IlvDiagrammerException

Deserializes a data source from the specified DOM element.

Deserializing a data source means reading its parameters from an XML configuration file. Deserializing a data source must not be confused with requesting the data source to read data into the diagram component.

This method reads the class name of the data source, creates an instance of this class, and then calls deserializeImpl(org.w3c.dom.Element) to let subclasses read their own configuration parameters.

Parameters:

element - The DOM element from which the data source parameters are read.

baseURL - The URL from which the configuration is being read. URL parameters of this data source may be relative to this base URL.

Throws:

IlvDiagrammerException - If an exception occurs while deserializing the data source. This exception will usually contain a "cause", that is to say the original low-level exception that caused the operation to fail.

deserializeImpl

protected abstract void deserializeImpl(Element element)
                                 throws IlvDiagrammerException

This method must be implemented by subclasses to read their parameters from an XML configuration file.

Parameters:

element - The DOM element to which the data source parameters are written.

Throws:

IlvDiagrammerException - If an exception occurs while deserializing the data source.

getBaseURL

protected URL getBaseURL()

Returns the base URL to or from which this data source is being deserialized. This URL can be used to save URL parameters of the data source as relative URLs.