dviner 2002/12/27 10:27:28
Added: java/scratchpad/xnode build.bat build.xml
java/scratchpad/xnode/src/org/apache/xnode XNode.java
XNodeException.java XNodeFactory.java
XNodeState.java XNodeStore.java
Log:
Initial checkin of code directly from Murray Altheim which is the XNode API.
We still need
an implementation of the api, but this is the first step.
--dviner
Revision Changes Path
1.1 xml-xindice/java/scratchpad/xnode/build.bat
Index: build.bat
===================================================================
@echo off
if "%JAVA_HOME%" == "" goto error
if not "%LIB_HOME%" == "" goto skip
set LIB_HOME=..\..\..\java\lib
:skip
echo.
echo Xindice Build System
echo --------------------
set ANT_HOME=..\..\..\java\lib
set LOCALCLASSPATH=%JAVA_HOME%\lib\tools.jar
for %%i in (%LIB_HOME%\*.jar) do call ..\..\..\bin\lcp.bat %%i
echo.
echo Building with classpath %LOCALCLASSPATH%
echo.
echo Starting Ant...
%JAVA_HOME%\bin\java.exe -Dant.home="%ANT_HOME%" -classpath
"%LOCALCLASSPATH%" org.apache.tools.ant.Main %1 %2 %3 %4 %5
goto end
:error
echo "ERROR: JAVA_HOME not found in your environment."
echo.
echo "Please, set the JAVA_HOME variable in your environment to match the"
echo "location of the Java Virtual Machine you want to use."
goto end
:end
set LOCALCLASSPATH=
set ANT_HOME=
set LIB_HOME=
1.1 xml-xindice/java/scratchpad/xnode/build.xml
Index: build.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--
Build file for XNode Scratchpad
Notes:
This is a build file for use with the Jakarta Ant java build tool.
How to build:
To build, run
cd $XINDICE_HOME/java/scratchpad/node
Build:
../../../bin/ant build
How to run:
We need an implementation of this API.
-->
<project name="xnode-scratchpad" default="build" basedir=".">
<!-- =================================================================== -->
<!-- Initializes the build process -->
<!-- =================================================================== -->
<!-- default directory structure definitions -->
<property name="xindice.home" value="../../../"/>
<property name="root.dir" value="."/>
<property name="jar.dir" value="${root.dir}/../../lib"/>
<property name="src.dir" value="${root.dir}/src"/>
<property name="build.dir" value="${root.dir}/classes"/>
<!-- classpath to use within project -->
<path id="project.class.path">
<!-- compiled classes directory -->
<pathelement location="${build.dir}"/>
<!-- all jars in jar directory -->
<fileset dir="${jar.dir}">
<include name="*.jar"/>
</fileset>
<!-- system property, environment classpath -->
<pathelement path="${java.class.path}"/>
</path>
<target name="init">
<tstamp/>
<property name="name" value="xnode"/>
<property name="version" value="0.1"/>
</target>
<!-- =================================================================== -->
<!-- Prepares the build directory -->
<!-- =================================================================== -->
<target name="prepare" depends="init">
<mkdir dir="${build.dir}"/>
</target>
<!-- =================================================================== -->
<!-- Compiles the source -->
<!-- =================================================================== -->
<target name="compile" depends="prepare">
<echo message="Compiling Xindice XNode - Scratchpad"/>
<javac srcdir="${src.dir}"
destdir="${build.dir}"
classpathref="project.class.path"
debug="on"
/>
</target>
<target name="build" depends="init, compile">
<jar jarfile="${xindice.home}/java/lib/xnode-0.1.jar"
basedir="${build.dir}">
</jar>
</target>
<!-- =================================================================== -->
<!-- Cleans everything -->
<!-- =================================================================== -->
<target name="clean">
<delete dir="${build.dir}"/>
</target>
</project>
1.1
xml-xindice/java/scratchpad/xnode/src/org/apache/xnode/XNode.java
Index: XNode.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999,2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "XNode" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many individuals
* on behalf of the Apache Software Foundation and was originally based on
* software copyright (c) 2001, Sun Microsystems, Inc., http://www.sun.com.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xnode;
import org.w3c.dom.*;
import java.util.Set;
/** An abstract class of an object acting as a container for XML content,
* providing a envelope element and an extensible metadata container for
* attributes such as a node ID (nid), timestamps, etc.
*
* <p>An example of such markup (wrapping an XHTML document) might appear
as: </p>
* <pre>
* <xnode:Envelope xmlns:xnode="http://www.apache.org/xnode/1.0/";
* xnode:id="n3892">
* <xnode:Header
* xnode:created="2001-10-22T18:33:56"
* xnode:modified="2001-10-24T09:11:37">
* <xnode:Property
* xnode:name="type"
* xnode:value="application/xhtml+xml"/>
* </xnode:Header>
* <xnode:Body>
* <html xmlns="http://www.w3.org/1999/xhtml">
* [document content]
* </html>
* </xnode:Body>
* </xnode:Envelope>
* </pre>
* <p>
* Substituting "SOAP-ENV" for "xnode", this is notably similar to a
* very simplified SOAP (which for having "Simple" in its title isn't in
* the end all that simple).
* </p>
* <p><b>Note 1:</b>
* The protected methods in this class are generally set by XNodeFactory
* or XNodeStore.
* </p>
* <p><b>Note 2:</b>
* Optional XNode metadata extensions use a Set of name-value pairs,
* represented in XML markup as <tt><xnode:Property></tt> child
elements
* on the <tt><xnode:Header></tt> element. This extension mechanism
* is backward compatible with earlier XNode versions. XNode 1.0 does not
* describe any specific extensions (i.e., they are <i>extensions</i>).
* </p>
* <p><a id="note3" name="note3"><b>Note 3:</b></a> in general,
* serializations of entire XNodes are more efficiently created from the
* <code>[EMAIL PROTECTED]
XNodeFactory#serializeXNode(XNode,boolean)}</code> method
* than using either <tt>toString()</tt> method, since it would be necessary
* to create an XML parser instance for each method call. If
<tt>toString()</tt>
* is unimplemented, it is appropriate to throw an XNodeException rather
* than return an incorrect serialization.</p>
*
* @author Murray Altheim, Sun Microsystems, Inc.
* @version $Id: XNode.java,v 1.1 2002/12/27 18:27:28 dviner Exp $
* @since JDK1.3
*/
public abstract class XNode
{
/** A String containing a URI reference identifying the XNode XML
Namespace.
* The value for XNode 1.0 is:
* <pre>
* http://www.apache.org/xnode/1.0/
* </pre>
*/
public final static String XMLNS_xnode =
"http://www.apache.org/xnode/1.0/";;
/** A String used as the default XML Namespace prefix for XNode 1.0. Note
* that this string <b>should not</b> include a colon character, eg.,
"xnode".
*/
public static String XMLNS_pfx = "xnode";
/** A String containing the local name of the
<tt><xnode:Envelope></tt> element. */
public final static String ELT_ENVELOPE = "Envelope";
/** A String containing the local name of the
<tt><xnode:Header></tt> element. */
public final static String ELT_HEADER = "Header";
/** A String containing the local name of the <tt><xnode:Body></tt>
element. */
public final static String ELT_BODY = "Body";
/** A String containing the local name of the
<tt><xnode:Property></tt> element. */
public final static String ELT_PROPERTY = "Property"; // new 2002-04
/** A String containing the local name of the <tt>xnode:id</tt>
attribute. */
public final static String ATTR_ID = "id";
/** A String containing the local name of the <tt>xnode:created</tt>
attribute. */
public final static String ATTR_CREATED = "created";
/** A String containing the local name of the <tt>xnode:modified</tt>
attribute. */
public final static String ATTR_MODIFIED = "modified";
/** A String containing the local name of the <tt>xnode:name</tt>
attribute. */
public final static String ATTR_NAME = "name"; // new 2002-04
/** A String containing the local name of the <tt>xnode:value</tt>
attribute. */
public final static String ATTR_VALUE = "value"; // new 2002-04
/* A String containing the required XNode ID identifier. */
private String nid;
// ............
/** Minimal constructor with a required String ID <tt>id</tt>.
*
* @param id the XNode ID.
* @throws XNodeException if the ID value is not an XML Name.
*/
protected XNode( String id ) throws XNodeException
{
setId(id);
}
/** Minimal constructor with a required String ID <tt>id</tt> and
* an XML DOM Node <tt>content</tt>.
*
* @param id the XNode ID.
* @param content the DOM Node used as XNode content.
* @throws XNodeException if the ID value is not an XML Name.
*/
protected XNode( String id, Node content ) throws XNodeException
{
setId(id);
setContentAsDOM(content);
}
/** Sets the ID of this XNode to the String <tt>id</tt>. Implementations
* should check to see that the ID is not already set and that the value
* is a valid XML Name.
*
* @param id the XNode ID.
* @throws XNodeException if already set, or is not an XML Name.
*/
protected void setId( String id ) throws XNodeException
{
this.nid = id;
}
/** Returns the Node ID of this XNode as a String.
*
* @return the XNode ID.
*/
public String getId()
{
return this.nid;
}
/** Sets the creation date of this XNode to the String <tt>timestamp</tt>.
*
* @param timestamp the creation timestamp as a String.
* @throws XNodeException if already set.
*/
protected abstract void setCreated( String timestamp ) throws
XNodeException;
/** Returns the creation date of this XNode as a String.
*
* @return the creation date of this XNode.
*/
public abstract String getCreated();
/** Sets the modification date of this XNode to the String
<tt>timestamp</tt>.
*
* @param timestamp the modification timestamp as a String.
*/
protected abstract void setModified( String timestamp );
/** Returns the modification date of this XNode as a String.
*
* @return the modification date of this XNode, null if
not set.
*/
public abstract String getModified();
/** Sets the named property <tt>name</tt> of this XNode to the String
<tt>value</tt>.
* If the property has already been set, its value is replaced. If the
property
* has been set and the provided value is null, the named property is
removed.
*
* @param name the property name.
* @param value the property value.
* @throws NullPointerException if either name or value parameter is
null.
*/
protected abstract void setProperty( String name, String value ) throws
NullPointerException;
/** Returns the named property <tt>name</tt> of this XNode as a String,
* null if it has not been set.
*
* @param name the property name.
* @return the property value, null if not set.
* @throws NullPointerException if the name parameter is null.
*/
public abstract String getProperty( String name ) throws
NullPointerException;
/** Returns a Set containing the named properties of this XNode,
* null if none have been set.
*
* @return the Set of named properties (as Strings).
*/
public abstract Set getProperties();
/** Sets the content of this XNode to the DOM Node <tt>content</tt>;
* this does allow the content to be set to null. The provided DOM node
* <b>should not</b> already include the XNode envelope. Note that the
* created and modified timestamps for this XNode are not set by this
method.
*
* @param content the Node to set as the content of this XNode.
* @throws XNodeException if there is existing content.
*/
protected abstract void setContentAsDOM( Node content ) throws
XNodeException;
/** Modifies this XNode by setting its content to the DOM Node
<tt>content</tt>;
* this does allow the content to be set to null. The provided DOM node
* <b>should not</b> already include the XNode envelope. Note that the
* created and modified timestamps for this XNode are not set by this
method.
*
* @param content the Node to set as the content of this XNode.
* @throws XNodeException if any problem occurs during modification.
*/
protected abstract void modifyContentAsDOM( Node content ) throws
XNodeException;
/** Returns a DOM Node representation of this XNode's content (excluding
the
* XNode envelope), null if has not been set.
*
* @return the DOM Node containing this XNode's content.
*/
public abstract Node getContentAsDOM() throws XNodeException;
/** Returns a String representation of this XNode, including the XNode
envelope.
* If the XNode's content is null or empty, this will still return the
envelope.
* See <a href="#note3">Note 3</a> for admonitions on using this method.
*
* @return a String representation of this XNode.
*/
public abstract String toString();
/** Returns a String representation of this XNode, including the envelope
* if <tt>includeEnvelope</tt> is true.
* See <a href="#note3">Note 3</a> for admonitions on using this method.
*
* @return a String representation of this XNode.
*/
public abstract String toString( boolean includeEnvelope );
} // end org.apache.xnode.XNode
1.1
xml-xindice/java/scratchpad/xnode/src/org/apache/xnode/XNodeException.java
Index: XNodeException.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999,2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "XNode" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many individuals
* on behalf of the Apache Software Foundation and was originally based on
* software copyright (c) 2001, Sun Microsystems, Inc., http://www.sun.com.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xnode;
/** Defines an exception thrown during XNode node generation and database
processing.
*
* <p>
* A class that extends Exception for errors that occur during XNode
* processing, including an option to capture the processor state
* when the XNodeException occurred.
* </p>
* <p><b><a id="NOTE_STATE" name="NOTE_STATE">Processing States</a>:</b>
* Processing states are defined as enumerated type objects in
org.apache.xnode.XNodeState.
* </p>
*
* @author Murray Altheim, Sun Microsystems, Inc.
* @version $Id: XNodeException.java,v 1.1 2002/12/27 18:27:28 dviner Exp $
* @since JDK1.3
* @see org.apache.xnode.XNodeState
* @see java.lang.Exception
*/
public class XNodeException extends Exception
{
/* An enumerated type object indicating processing state at the time of
the exception. */
private XNodeState state = XNodeState.UNDEFINED;
/* A java.lang.Exception container used when tunnelling. */
private Exception exception;
// ............
/** Constructor for XNodeException provided with an error String
<tt>message</tt>.
*
* @param message the exception message.
*/
public XNodeException( String message )
{
super(message);
this.exception = null;
}
/** Constructor for XNodeException provided with an int <tt>errorcode</tt>
* and an error String <tt>message</tt>.
* <p>See <a href="#NOTE_STATE">Processing State codes</a>.</p>
*
* @param state the processing state when the Exception
occurred.
* @param message the exception message.
* @see org.apache.xnode.XNodeStore for processing state codes.
*/
public XNodeException( XNodeState state, String message )
{
super(message);
this.state = state;
this.exception = null;
}
/** Constructor for XNodeException tunnelling an original Exception.
*
* @param exception the original Exception.
*/
public XNodeException( Exception exception )
{
super();
this.exception = exception;
}
/** Constructor for XNodeException tunnelling an original Exception,
* including an XNodeState state indicator.
* <p>See <a href="#NOTE_STATE">Processing State codes</a>.</p>
*
* @param state the processing state when the Exception
occurred.
* @param exception the original Exception.
* @see org.apache.xnode.XNodeStore for processing state codes.
*/
public XNodeException( XNodeState state, Exception exception )
{
super();
this.state = state;
this.exception = exception;
}
/** Constructor for XNodeException including a message and tunnelling an
original Exception.
*
* @param message the Exception message String.
* @param exception the original Exception.
*/
public XNodeException( String message, Exception exception )
{
super(message);
this.exception = exception;
}
/** Constructor for XNodeException tunnelling an original Exception,
* including a state indicator, and a message String.
* <p>See <a href="#NOTE_STATE">Processing State codes</a>.</p>
*
* @param state the processing state when the Exception
occurred.
* @param message the Exception message String.
* @param exception the original Exception.
* @see org.apache.xnode.XNodeStore for processing state codes.
*/
public XNodeException( XNodeState state, String message, Exception
exception )
{
super(message);
this.state = state;
this.exception = exception;
}
/** Returns the tunnelled Exception, if any.
*
* @return the tunnelled Exception, null if there is
none.
*/
public Exception getException()
{
return exception;
}
/** Returns the processor state at the time of the Exception. If this
* has not been set, returns XNodeStore.UNDEFINED.
*
* @see org.apache.xnode.XNodeState
* @return an XNodeState state indicator.
*/
public XNodeState getState()
{
return state;
}
/** Returns the message for this XNodeException.
*
* <p>If the tunnelled Exception and this XNodeException has no message
* of its own, returns the message of the tunnelled Exception.</p>
*
* @return the warning or error message.
*/
public String getMessage()
{
String message = super.getMessage();
if ( message == null && exception != null ) return
exception.getMessage();
else return message;
}
/** Overrides <tt>toString()</tt> to return a String representation of
this
* XNodeException, substituting any tunnelled Exception if available.
*
* @return a String representation of this
XNodeException.
*/
public String toString()
{
if ( exception == null ) return super.toString();
else return exception.toString();
}
} // end org.apache.xnode.XNodeException
1.1
xml-xindice/java/scratchpad/xnode/src/org/apache/xnode/XNodeFactory.java
Index: XNodeFactory.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999,2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "XNode" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many individuals
* on behalf of the Apache Software Foundation and was originally based on
* software copyright (c) 2001, Sun Microsystems, Inc., http://www.sun.com.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xnode;
import org.w3c.dom.Node;
import java.io.Writer;
/** Provides an API of a factory for creating XNode objects.
*
* @author Murray Altheim, Sun Microsystems, Inc.
* @version $Id: XNodeFactory.java,v 1.1 2002/12/27 18:27:28 dviner Exp $
* @since JDK1.3
*/
public interface XNodeFactory
{
/** Returns an empty XNode, provided a String ID <tt>id</tt>.
*
* @param id the XNode unique identifier
* @return an XNode whose ID is 'id'
* @throws XNodeException if an error occurs during creation
*/
public XNode createXNode( String id ) throws XNodeException;
/** Returns an XNode provided a String ID <tt>id</tt> and a DOM Node
* <tt>node</tt>. If <tt>node</tt> is null, this method will act
* exactly as <tt>createXNode(id)</tt>, ie., provide an empty XNode.
*
* @param id the XNode ID.
* @param node the DOM Node to be enclosed in the XNode.
* @return the created XNode.
* @throws XNodeException if an error occurs during creation.
*/
public XNode createXNode( String id, Node node ) throws XNodeException;
/** Returns an XNode provided a DOM Node <tt>node</tt>, assuming
* the provided node's content is a serialization of an XNode
* (some minor validation will necessarily occur).
*
* @param node the DOM Node to be processed as XNode content.
* @return the recreated XNode.
* @throws XNodeException if an error occurs during recreation.
*/
public XNode recreateXNode( Node node ) throws XNodeException;
/** Provided with an XNode <tt>xnode</tt>, returns a DOM Document
representation.
* If <tt>includeEnvelope</tt> is true, the <tt>xnode:Envelope</tt> will
be included.
*
* @param xnode the XNode to be processed.
* @param includeEnvelope if true, include the xnode:Envelope.
* @return a DOM Document representation of the XNode
(as a Node).
* @throws XNodeException if an error occurs during processing.
*/
public Node getXNodeAsDOM( XNode xnode, boolean includeEnvelope ) throws
XNodeException;
/** Writes an XML serialization of the XNode <tt>xnode</tt> to the
supplied
* Writer <tt>writer</tt>. If <tt>includeEnvelope</tt> is true, the
* <tt><xnode:Envelope></tt> will be included.
*
* @param xnode the XNode to be serialized
* @param writer the Writer receiving the output
* @param includeEnvelope if true, include the xnode:Envelope
* @throws XNodeException if an error occurs during serialization
*/
public void serializeXNode( Writer writer, XNode xnode, boolean
includeEnvelope ) throws XNodeException;
/** Provided with an XNode <tt>xnode</tt>, returns an XML serialization as
a
* String. If <tt>includeEnvelope</tt> is true, the
<tt>xnode:Envelope</tt>
* will be included.
*
* @param xnode the XNode to be serialized.
* @param includeEnvelope if true, include the xnode:Envelope.
* @return the String representation of the XNode.
* @throws XNodeException if an error occurs during serialization.
*/
public String serializeXNode( XNode xnode, boolean includeEnvelope )
throws XNodeException;
} // end org.apache.xnode.XNodeFactory
1.1
xml-xindice/java/scratchpad/xnode/src/org/apache/xnode/XNodeState.java
Index: XNodeState.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999,2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "XNode" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many individuals
* on behalf of the Apache Software Foundation and was originally based on
* software copyright (c) 2001, Sun Microsystems, Inc., http://www.sun.com.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xnode;
/** Defines a set of enumerated type objects to declare a fixed set of
* state values for XNode processing.
*
* @author Murray Altheim, Sun Microsystems, Inc.
* @version $Id: XNodeState.java,v 1.1 2002/12/27 18:27:28 dviner Exp $
* @since JDK1.3
*/
public final class XNodeState
{
private XNodeState() {} // prohibit creation of new states
/** A state variable indicating an undefined state. */
public static final XNodeState UNDEFINED = new XNodeState();
/** A state variable indicating a exception or error state.
* @deprecated
*/
public static final XNodeState EXCEPTION = new XNodeState();
/** A state variable indicating a exception or error state. */
public static final XNodeState ERROR = new XNodeState();
/** A state variable indicating a initialization state. */
public static final XNodeState INITIALIZE = new XNodeState();
/** A state variable indicating a connecting state. */
public static final XNodeState CONNECT = new XNodeState();
/** A state variable indicating a disconnecting state. */
public static final XNodeState DISCONNECT = new XNodeState();
/** A state variable indicating a state of XML processing. */
public static final XNodeState XML_PROCESSING = new XNodeState();
/** A state variable indicating a query event. */
public static final XNodeState QUERY = new XNodeState();
/** A state variable indicating a collection addition event. */
public static final XNodeState COLLECTION_ADD = new XNodeState();
/** A state variable indicating a collection retrieval event. */
public static final XNodeState COLLECTION_GET = new XNodeState();
/** A state variable indicating an collection indexing event. */
public static final XNodeState COLLECTION_INDEX = new XNodeState();
/** A state variable indicating a collection deletion event. */
public static final XNodeState COLLECTION_CLOSE = new XNodeState();
/** A state variable indicating a collection deletion event. */
public static final XNodeState COLLECTION_DELETE = new XNodeState();
/** A state variable indicating a node creation event. */
public static final XNodeState NODE_CREATE = new XNodeState();
/** A state variable indicating a node addition event. */
public static final XNodeState NODE_ADD = new XNodeState();
/** A state variable indicating a node modification event. */
public static final XNodeState NODE_MODIFY = new XNodeState();
/** A state variable indicating a node retrieval event. */
public static final XNodeState NODE_GET = new XNodeState();
/** A state variable indicating a node deletion event. */
public static final XNodeState NODE_DELETE = new XNodeState();
/** A state variable indicating a node re-creation event. */
public static final XNodeState NODE_RECREATE = new XNodeState();
} // end org.apache.xnode.XNodeState
1.1
xml-xindice/java/scratchpad/xnode/src/org/apache/xnode/XNodeStore.java
Index: XNodeStore.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999,2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "XNode" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many individuals
* on behalf of the Apache Software Foundation and was originally based on
* software copyright (c) 2001, Sun Microsystems, Inc., http://www.sun.com.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xnode;
import org.xmldb.api.base.*;
import org.w3c.dom.Node;
import java.net.URL;
import java.util.Hashtable;
import java.util.Iterator;
/** Defines a database manager API for XML Node (XNode) content.
*
* @author Murray Altheim, Sun Microsystems, Inc.
* @version $Id: XNodeStore.java,v 1.1 2002/12/27 18:27:28 dviner Exp $
* @since JDK1.3
*/
public interface XNodeStore
{
/** A String indicator used to refer to all maintained collections. */
// Unicode INFINITY (an arbitrary, untypeable name)
public static final String ALL_COLLECTIONS = String.valueOf(0x221E);
// ............
/** Return the URL of the root Collection as a String.
*/
public String getRoot();
/** Set the URL of the root Collection to the String <tt>root</tt>.
* If the database is already running, this will throw an XNodeException.
*
* @throws XNodeException if a database connection has already been
made.
*/
public void setRoot( String root ) throws XNodeException;
/** Gets the state of this XNodeStore, as according to the processing
* states enumerated in XNodeState.
*
* @return the current state of this XNodeStore
* @see org.apache.xnode.XNodeState
*/
public XNodeState getState();
/** Make a database connection to the root Collection and establish
service.
* <tt>timeout</tt> is the maximum number of seconds to wait for the
Collection
* Manager to open before abandoning. Setting this to zero will cause it
to wait
* indefinitely.
*
* @param timeout time in seconds to wait before abandoning.
* @throws XNodeException if unable to make the connection
*/
public void connect( int timeout ) throws XNodeException;
/** Disconnect any connection to the root Collection and close down all
services.
*
* @throws XNodeException if an error occurs during this process.
*/
public void disconnect() throws XNodeException;
/** Returns true if a connection with database has been made and its
service is available.
*
* @return true if a database connection has been made.
*/
public boolean isConnected();
// Collection operations .................................
/** Create an new Collection identified by the ID <tt>cid</tt>, with
* a boolean <tt>overwrite</tt> that when true will overwrite an existing
* Collection with the same ID. If false, throws an XNodeException.
*
* @param cid the Collection ID String.
* @param overwrite if true, will overwrite any existing
Collection.
* @throws XNodeException if unable to create the Collection
*/
public void createCollection( String cid, boolean overwrite ) throws
XNodeException;
/** Return an existing XML database Collection whose ID is <tt>cid</tt>.
*
* @param cid the Collection ID String.
* @return the Collection matching ID 'cid'.
* @throws XNodeException if unable to locate the Collection
*/
public Collection getCollection( String cid ) throws XNodeException;
/** Return an Iterator over all available XML database Collections.
*
* @return an Iterator over all available Collections.
* @throws XNodeException if unable to provide the Iterator.
*/
public Iterator getCollections() throws XNodeException;
/** Return an Iterator over the index of XNode IDs within the
* Collection <tt>cid</tt>, or null if empty.
*
* @param cid the Collection ID String.
* @return an Iterator containing the IDs of all XNodes
in the Collection.
* @throws XNodeException if the Collection ID is invalid or the
Collection(s) did not exist.
*/
public Iterator getCollectionIndex( String cid ) throws XNodeException;
/** Close an existing Collection <tt>cid</tt>. If the value equals
* XNodeStore.ALL_COLLECTIONS, will close all open Collections.
*
* @param cid the Collection ID String.
* @throws XNodeException if the Collection ID is invalid or the
Collection(s) did not exist.
*/
public void closeCollection( String cid ) throws XNodeException;
/** Delete an existing XML database Collection <tt>cid</tt>. If the ID
value
* is <tt>ALL_COLLECTIONS</tt>, will delete all existing Collections.
*
* @param cid the Collection ID String.
* @throws XNodeException if the Collection ID is invalid or the
Collection(s) did not exist.
*/
public void deleteCollection( String cid ) throws XNodeException;
// XNode operations .......................................
/** Returns true if an XNode with ID <tt>nid</tt> exists in the Collection
* with ID <tt>cid</tt>. Throws an XNodeException if the specified
Collection
* does not exist or either ID is invalid.
*
* @param cid the Collection ID String.
* @param nid the ID String for the stored XNode.
* @return true if the XNode exists.
* @throws XNodeException if the Collection does not exist or either ID
is invalid.
*/
public boolean nodeExists( String cid, String nid ) throws XNodeException;
/** Retrieves an XNode with ID <tt>nid</tt> from Collection with ID
<tt>cid</tt>,
* or null if unable to retrieve.
* Note that the retrieved XNode content includes its wrapper elements
and is
* returned as a DOM Node, then reconstituted as an XNode object.
*
* @param cid the Collection ID String.
* @param nid the XNode ID String.
* @return the retrieved XNode.
* @throws XNodeException if the Collection is unavailable or either ID
is invalid.
*/
public XNode getXNode( String cid, String nid ) throws XNodeException;
/** Insert a new XNode with ID <tt>nid</tt> whose content is the String
<tt>content</tt>,
* into the Collection with ID <tt>cid</tt>, returning the ID value of
the added XNode.
* <p><b>Note:</b> This method implies that the supplied content String
be well-formed
* XML, as it will by necessity be parsed into a DOM Node. This is a
convenience class
* for those unwilling to parse their own content, the downside is that
if the content
* is not well-formed, an exception is thrown and nothing gets stored.
* </p>
*
* @param cid the Collection ID String.
* @param nid the ID String of the stored XNode.
* @param content the String content to be parsed into a DOM
Node.
* @return the new XNode.
* @throws XNodeException if unable to add the XNode.
*/
public XNode addXNode( String cid, String nid, String content ) throws
XNodeException;
/** Insert a new XNode with ID <tt>nid</tt> whose content is the DOM Node
<tt>node</tt>,
* into the Collection with ID <tt>cid</tt>, returning the ID value of
the added XNode.
*
* @param cid the Collection ID String.
* @param nid the ID String for the stored XNode.
* @param node the DOM Node content.
* @return the new XNode.
* @throws XNodeException if unable to add the XNode.
*/
public XNode addXNode( String cid, String nid, Node node ) throws
XNodeException;
/** Modify an XNode with ID <tt>nid</tt> in Collection <tt>cid</tt>,
replacing its
* contents with the contents of the String <tt>content</tt>.
*
* @param cid the Collection ID String.
* @param nid the ID String of the stored XNode.
* @param content the String content to be parsed into a DOM
Node.
* @return the provided XNode
* @throws XNodeException if unable to modify the XNode.
*/
public XNode modifyXNode( String cid, String nid, String content ) throws
XNodeException;
/** Modify an XNode with ID <tt>nid</tt> whose content is the DOM Node
<tt>node</tt>,
* in the Collection with ID <tt>cid</tt>, returning the added XNode.
*
* @param cid the Collection ID String.
* @param nid the ID String for the stored XNode.
* @param node the DOM Node content.
* @return the added XNode
* @throws XNodeException if unable to modify the XNode.
*/
public XNode modifyXNode( String cid, String nid, Node node ) throws
XNodeException;
/** Write the XNode <tt>xnode</tt> to the Collection <tt>cid</tt>, by
* locating the existing XNode (by ID) and replacing it with the provided
* one.
* <p><b>Note:</b> This method is generally used to set metadata on an
existing
* XNode, so creation or modification timestamps are not altered.</p>
*
* @param cid the Collection ID String.
* @param xnode the new XNode to overwrite the old.
* @return the stored XNode
* @throws XNodeException if unable to write the XNode to the
Collection.
*/
public XNode writeXNode( String cid, XNode xnode ) throws XNodeException;
/** Delete an XNode identified by ID <tt>nid</tt> from the Collection
<tt>cid</tt>.
*
* @param cid the Collection ID String.
* @param nid the XNode ID String.
* @throws XNodeException if the Collection is unavailable, either ID
is invalid, or otherwise unable to delete.
*/
public void deleteXNode( String cid, String nid ) throws XNodeException;
/** For an XNode with ID <tt>nid</tt> in Collection <tt>cid</tt>, set the
* named property <tt>name</tt> whose value is the String <tt>value</tt>.
* <p><b>Note:</b> this only modifies the property of the supplied XNode
* and does not involve any transactions with the database, which must be
* performed separately.</p>
*
* @param xnode the XNode to which the property is set.
* @param name the name of the property.
* @param value the value of the property.
* @throws XNodeException if the XNode does not exist or the property
is invalid.
*/
public void setXNodeProperty(
XNode xnode, String name, String value ) throws XNodeException;
/** For an XNode with ID <tt>nid</tt> in Collection <tt>cid</tt>, set the
* named properties provided by the key-value pairs found in the
Hashtable
* <tt>properties</tt>. This is to provide some efficiency over setting
* properties individually, which requires a save operation for each
property.
* <p><b>Note:</b> this only modifies the properties of the supplied
XNode
* and does not involve any transactions with the database, which must be
* performed separately.</p>
*
* @param xnode the XNode to which the properties are to be
set.
* @param properties the Hashtable containing the properties.
* @throws XNodeException if the XNode does not exist or any of the
properties are invalid.
*/
public void setXNodeProperties(
XNode xnode, Hashtable properties ) throws XNodeException;
/** Query the database for XNodes matching the XPath Query <tt>path</tt>,
* searching in the Collection <tt>cid</tt> and returning an Iterator
* over the matching XNodes.
* The resolution of XML namespace prefixes is done by setting each
* namespace using <tt>setNamespace()</tt>.
*
* @param cid the Collection ID String.
* @param path the XPath query String.
* @return an Iterator over the matching XNodes.
* @throws XNodeException if the query fails.
*/
public Iterator queryXNode( String cid, String path ) throws
XNodeException;
/** Sets a namespace mapping in the internal namespace map used to evaluate
* queries. If <tt>prefix</tt> is null or empty, the URI is associated
with
* the default namespace. An exception is thrown if the URI is null or
empty.
*
* @throws XNodeException if any errors occur.
*/
public void setNamespace( String prefix, String uri ) throws
XNodeException;
/** Clears any namespace mappings in the internal namespace map used to
* evaluate queries.
*
* @throws XNodeException if any errors occur.
*/
public void clearNamespaces() throws XNodeException;
} // end org.apache.xnode.XNodeStore
