|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
|
+--javax.swing.undo.UndoableEditSupport
|
+--net.sourceforge.gxl.GXLDocument
Represents a GXL document responsible for reading and writing GXL files.
The top gxl element is automatically created and cannot be removed. To add
other elements to this document, add them to the gxl element which is accessible through the
getDocumentElement method or any of it's children.
To create a simple gxl document and write it to file, follow these basic steps:
// Create document and elements
GXLDocument gxlDocument = new GXLDocument();
GXLGraph graph = new GXLGraph("graph1");
GXLNode node1 = new GXLNode("node1");
GXLNode node2 = new GXLNode("node2");
GXLEdge edge1 = new GXLEdge(node1, node2);
// Build the tree structure
graph.add(node1);
graph.add(node2);
graph.add(edge1);
gxlDocument.getDocumentElement().add(graph);
// Write the document to file
try {
gxlDocument.write(new File("MyFirstGXLDocument.gxl"));
}
catch (IOException ioe) {
System.out.println("Error while writing to file: " + ioe);
}
Validation
The GXL structure is concurrently being validated as the document and elements are being built
and will throw a GXLValidationException if an operation is attempted that would
render the GXL structure invalid. The exception of this is the permission to temporarily create
dangling tentacles as described below. The same validation mechanism is used when reading a document
so as to provide consistent exceptions (apart from invalid XML documents which will be thrown
by the XML parser). For a full description of which types of GXLValidationsExceptions
that can be thrown and when, see GXLValidationException.
Undo Support
GXLDocument extends UndoableEditSupport and thusly provides undo support.
This is however only true of changes made that the document is aware of, namely to elements that is
already part of the documents tree structure. In the example above, only the last tree change - adding
the graph to the top gxl element - is undoable.
Dangling Tentacles
To enhance usability the introduction of dangling tentacles is allowed. A dangling tentacle will occur
when an edge or a relation is inserted into a GXLDocument and one of it's tentacles point
to a non-existent node. This is a validation error in GXL and the GXLDocument will throw
if any of the write methods is called. The rationale behind allowing it is because GXL
doesn't place any restricions on the order of appearance of nodes and edges in the file, permitting
an edge to be placed before the referenced node. Besides if it weren't allowed, the example above
would throw an exception if the line adding the edge would be placed above the lines adding the nodes.
In particular any edge or relation that is not part of a GXLDocument will always have
dangling tentacles since the GXLDocument is responsible for matching id references to
specific GXLElements.
For more information about the GXL file format and it's uses, see http://www.gupro.de/GXL
GXLValidationException,
UndoableEditSupport| Field Summary |
| Fields inherited from class javax.swing.undo.UndoableEditSupport |
compoundEdit, listeners, realSource, updateLevel |
| Constructor Summary | |
GXLDocument()
Creates a blank GXLDocument, only containing the top gxl element. |
|
GXLDocument(File gxlFile)
Parses the specified file and builds the GXL document structure out of it. |
|
GXLDocument(InputStream is)
Parses the specified InputStream and builds the GXL document structure out of it. |
|
GXLDocument(URL url)
Parses the resource specified by the url and builds the GXL document structure out of it. |
|
| Method Summary | |
void |
addGXLDocumentListener(GXLDocumentListener l)
Adds the specified document listener to receive document modification events. |
boolean |
containsID(String id)
Whether the specified id is used by any of the elements contained in this document. |
GXLLocalConnectionTentacle |
getDanglingTentacleAt(int i)
Returns the specified dangling tentacle. |
int |
getDanglingTentacleCount()
Returns the number of dangling tentacles contained in this document. |
GXLGXL |
getDocumentElement()
Returns the top gxl element.
|
GXLAttributedElement |
getElement(String id)
Returns the element with the specified id, or null if no element contained in this document has the specified id set. |
void |
removeGXLDocumentListener(GXLDocumentListener l)
Removes the specified document listener so that it no longer receives document modification events. |
void |
write(File file)
Writes this document to file. |
void |
write(OutputStream os)
Writes this document to an OutputStream. |
| Methods inherited from class javax.swing.undo.UndoableEditSupport |
_postEdit, addUndoableEditListener, beginUpdate, createCompoundEdit, endUpdate, getUndoableEditListeners, getUpdateLevel, postEdit, removeUndoableEditListener, toString |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
public GXLDocument()
gxl element.
public GXLDocument(File gxlFile)
throws IOException,
SAXException
gxlFile - The file containing the GXL to parse.
IOException - If the file doesn't exist or cannot be read.
SAXException - If the file doesn't contain a valid XML document.
GXLValidationException - If the file doesn't contain a valid GXL document.
public GXLDocument(URL url)
throws IOException,
SAXException
url - A URL pointing to a GXL resource.
IOException - If the resource doesn't exist or cannot be read.
SAXException - If the resource doesn't contain a valid XML document.
GXLValidationException - If the resource doesn't contain a valid GXL document.
public GXLDocument(InputStream is)
throws IOException,
SAXException
InputStream and builds the GXL document structure out of it.
is - An InputStream containing a GXL document.
IOException - If the resource doesn't exist or cannot be read.
SAXException - If the resource doesn't contain a valid XML document.
GXLValidationException - If the resource doesn't contain a valid GXL document.| Method Detail |
public void addGXLDocumentListener(GXLDocumentListener l)
l - The listener to register for event notification.public void removeGXLDocumentListener(GXLDocumentListener l)
l - The listener to unregister for event notification.public int getDanglingTentacleCount()
getDanglingTentacleAt(int),
GXLLocalConnection.containsDanglingTentacles()public GXLLocalConnectionTentacle getDanglingTentacleAt(int i)
i - The index of the specified tentacle.
getDanglingTentacleCount(),
GXLLocalConnection.containsDanglingTentacles()public GXLGXL getDocumentElement()
gxl element.
This element is automatically created when a GXLDocument is created and
always wraps all other elements in a GXL document.
gxl element.public boolean containsID(String id)
id - The specified id to search for.
public GXLAttributedElement getElement(String id)
id - The specified id to search for.
public void write(File file)
throws IOException
file - The file to write this document to.
IOException - If the file couldn't be written to.
IllegalArgumentException - If this document contains dangling tentacles.
public void write(OutputStream os)
throws IOException
OutputStream. Note that writing a document containing dangling tentacles
to file is prohibited since this would create an invalid GXL document.
os - The stream to write this document to.
IOException - If the stream couldn't be written to.
IllegalArgumentException - If this document contains dangling tentacles.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||