diff options
Diffstat (limited to 'sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java')
18 files changed, 3546 insertions, 0 deletions
diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/ChangeSummary.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/ChangeSummary.java new file mode 100644 index 0000000000..72d694da45 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/ChangeSummary.java @@ -0,0 +1,207 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +import java.util.List; + +/** + * A change summary is used to record changes to DataObjects, + * allowing applications to efficiently and incrementally update back-end storage when required. + */ +public interface ChangeSummary +{ + /** + * Indicates whether change logging is on (<code>true</code>) or off (<code>false</code>). + * @return <code>true</code> if change logging is on. + * @see #beginLogging + * @see #endLogging + */ + boolean isLogging(); + + /** + * Returns the {@link DataGraph data graph} associated with this change summary or null. + * @return the data graph. + * @see DataGraph#getChangeSummary + */ + DataGraph getDataGraph(); + + /** + * Returns a list consisting of all the {@link DataObject data objects} that have been changed while {@link #isLogging logging}. + * <p> + * The {@link #isCreated new} and {@link #isModified modified} objects in the List are references to objects + * associated with this ChangeSummary. + * The {@link #isDeleted deleted} objects in the List are references to objects + * at the time that event logging was enabled; + * <p> Each changed object must have exactly one of the following methods return true: + * {@link #isCreated isCreated}, + * {@link #isDeleted isDeleted}, or + * {@link #isModified isModified}. + * @return a list of changed data objects. + * @see #isCreated(DataObject) + * @see #isDeleted(DataObject) + * @see #isModified(DataObject) + */ + List /*DataObject*/ getChangedDataObjects(); + + /** + * Returns whether or not the specified data object was created while {@link #isLogging logging}. + * Any object that was added to the scope + * but was not in the scope when logging began, + * will be considered created. + * @param dataObject the data object in question. + * @return <code>true</code> if the specified data object was created. + * @see #getChangedDataObjects + */ + boolean isCreated(DataObject dataObject); + + /** + * Returns whether or not the specified data object was deleted while {@link #isLogging logging}. + * Any object that is not in scope but was in scope when logging began + * will be considered deleted. + * @param dataObject the data object in question. + * @return <code>true</code> if the specified data object was deleted. + * @see #getChangedDataObjects + */ + boolean isDeleted(DataObject dataObject); + + /** + * A setting encapsulates a {@link Property property} and a corresponding single value of the property's {@link Property#getType type}. + */ + public interface Setting + { + /** + * Returns the property of the setting. + * @return the setting property. + */ + Property getProperty(); + + /** + * Returns the value of the setting. + * @return the setting value. + */ + Object getValue(); + + /** + * Returns whether or not the property is set. + * @return <code>true</code> if the property is set. + */ + boolean isSet(); + } + + /** + * Returns a list of {@link ChangeSummary.Setting settings} + * that represent the property values of the given <code>dataObject</code> + * at the point when logging {@link #beginLogging() began}. + * <p>In the case of a {@link #isDeleted(DataObject) deleted} object, + * the List will include settings for all the Properties. + * <p> An old value setting indicates the value at the + * point logging begins. A setting is only produced for + * {@link #isModified modified} objects if + * either the old value differs from the current value or + * if the isSet differs from the current value. + * <p> No settings are produced for {@link #isCreated created} objects. + * @param dataObject the object in question. + * @return a list of settings. + * @see #getChangedDataObjects + */ + List /*ChangeSummary.Setting*/ getOldValues(DataObject dataObject); + + /** + * Clears the List of {@link #getChangedDataObjects changes} and turns change logging on. + * No operation occurs if logging is already on. + * @see #endLogging + * @see #isLogging + */ + void beginLogging(); + + /** + * An implementation that requires logging may throw an UnsupportedOperationException. + * Turns change logging off. No operation occurs if logging is already off. + * @see #beginLogging + * @see #isLogging + */ + void endLogging(); + + + /** + * Returns whether or not the specified data object was updated while {@link #isLogging logging}. + * An object that was contained in the scope when logging began + * and remains in the scope when logging ends will be considered potentially modified. + * <p> An object considered modified must have at least one old value setting. + * @param dataObject the data object in question. + * @return <code>true</code> if the specified data object was modified. + * @see #getChangedDataObjects + */ + boolean isModified(DataObject dataObject); + + /** + * Returns the ChangeSummary root DataObject - the object from which + * changes are tracked. + * When a DataGraph is used, this is the same as getDataGraph().getRootObject(). + * @return the ChangeSummary root DataObject + */ + DataObject getRootObject(); + + /** + * Returns a {@link ChangeSummary.Setting setting} for the specified property + * representing the property value of the given <code>dataObject</code> + * at the point when logging {@link #beginLogging() began}. + * <p>Returns null if the property was not modified and + * has not been {@link #isDeleted(DataObject) deleted}. + * @param dataObject the object in question. + * @param property the property of the object. + * @return the Setting for the specified property. + * @see #getChangedDataObjects + */ + Setting getOldValue(DataObject dataObject, Property property); + + /** + * Returns the value of the {@link DataObject#getContainer container} data object + * at the point when logging {@link #beginLogging() began}. + * @param dataObject the object in question. + * @return the old container data object. + */ + DataObject getOldContainer(DataObject dataObject); + + /** + * Returns the value of the {@link DataObject#getContainmentProperty containment property} data object property + * at the point when logging {@link #beginLogging() began}. + * @param dataObject the object in question. + * @return the old containment property. + */ + Property getOldContainmentProperty(DataObject dataObject); + + /** + * Returns the value of the {@link DataObject#getSequence sequence} for the data object + * at the point when logging {@link #beginLogging() began}. + * @param dataObject the object in question. + * @return the old containment property. + */ + Sequence getOldSequence(DataObject dataObject); + + /** + * This method is intended for use by service implementations only. + * Undoes all changes in the log to restore the tree of + * DataObjects to its original state when logging began. + * isLogging() is unchanged. The log is cleared. + * @see #beginLogging + * @see #endLogging + * @see #isLogging + */ + void undoChanges(); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataGraph.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataGraph.java new file mode 100644 index 0000000000..f583cbf0a3 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataGraph.java @@ -0,0 +1,76 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +import java.io.Serializable; + +/** + * A data graph is used to package a graph of {@link DataObject data objects} along with their + * metadata, that is, data describing the data. + * A data graph also contains a {@link #getChangeSummary change summary} + * which is used to record changes made to the objects in the graph. + */ + +public interface DataGraph extends Serializable +{ + /** + * Returns the root {@link DataObject data object} of this data graph. + * @return the root data object. + * @see DataObject#getDataGraph + */ + DataObject getRootObject(); + + /** + * Returns the {@link ChangeSummary change summary} associated with this data graph. + * @return the change summary. + * @see ChangeSummary#getDataGraph + */ + ChangeSummary getChangeSummary(); + + /** + * Returns the {@link Type type} with the given the {@link Type#getURI() URI}, + * or contained by the resource at the given URI, + * and with the given {@link Type#getName name}. + * @param uri the namespace URI of a type or the location URI of a resource containing a type. + * @param typeName name of a type. + * @return the type with the corresponding namespace and name. + */ + Type getType(String uri, String typeName); + + /** + * Creates a new root data object of the {@link #getType specified type}. + * An exception is thrown if a root object exists. + * @param namespaceURI namespace of the type. + * @param typeName name of the type. + * @return the new root. + * @throws IllegalStateException if the root object already exists. + * @see #createRootObject(Type) + * @see #getType(String, String) + */ + DataObject createRootObject(String namespaceURI, String typeName); + + /** + * Creates a new root data object of the specified type. + * An exception is thrown if a root object exists. + * @param type the type of the new root. + * @return the new root. + * @throws IllegalStateException if the root object already exists. + * @see #createRootObject(String, String) + */ + DataObject createRootObject(Type type); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataObject.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataObject.java new file mode 100644 index 0000000000..fb592fcf58 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/DataObject.java @@ -0,0 +1,1121 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +import java.io.Serializable; +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.Date; +import java.util.List; + +/** + * A data object is a representation of some structured data. + * It is the fundamental component in the SDO (Service Data Objects) package. + * Data objects support reflection, path-based accesss, convenience creation and deletion methods, + * and the ability to be part of a {@link DataGraph data graph}. + * <p> + * Each data object holds its data as a series of {@link Property Properties}. + * Properties can be accessed by name, property index, or using the property meta object itself. + * A data object can also contain references to other data objects, through reference-type Properties. + * <p> + * A data object has a series of convenience accessors for its Properties. + * These methods either use a path (String), + * a property index, + * or the {@link Property property's meta object} itself, to identify the property. + * Some examples of the path-based accessors are as follows: + *<pre> + * DataObject company = ...; + * company.get("name"); is the same as company.get(company.getType().getProperty("name")) + * company.set("name", "acme"); + * company.get("department.0/name") is the same as ((DataObject)((List)company.get("department")).get(0)).get("name") + * .n indexes from 0 ... implies the name property of the first department + * company.get("department[1]/name") [] indexes from 1 ... implies the name property of the first department + * company.get("department[number=123]") returns the first department where number=123 + * company.get("..") returns the containing data object + * company.get("/") returns the root containing data object + *</pre> + * <p> There are general accessors for Properties, i.e., {@link #get(Property) get} and {@link #set(Property, Object) set}, + * as well as specific accessors for the primitive types and commonly used data types like + * String, Date, List, BigInteger, and BigDecimal. + */ +public interface DataObject extends Serializable +{ + /** + * Returns the value of a property of either this object or an object reachable from it, as identified by the + * specified path. + * @param path the path to a valid object and property. + * @return the value of the specified property. + * @see #get(Property) + */ + Object get(String path); + + /** + * Sets a property of either this object or an object reachable from it, as identified by the specified path, + * to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void set(String path, Object value); + + /** + * Returns whether a property of either this object or an object reachable from it, as identified by the specified path, + * is considered to be set. + * @param path the path to a valid object and property. + * @see #isSet(Property) + */ + boolean isSet(String path); + + /** + * Unsets a property of either this object or an object reachable from it, as identified by the specified path. + * @param path the path to a valid object and property. + * @see #unset(Property) + */ + void unset(String path); + + /** + * Returns the value of a <code>boolean</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>boolean</code> value of the specified property. + * @see #get(String) + */ + boolean getBoolean(String path); + + /** + * Returns the value of a <code>byte</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>byte</code> value of the specified property. + * @see #get(String) + */ + byte getByte(String path); + + /** + * Returns the value of a <code>char</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>char</code> value of the specified property. + * @see #get(String) + */ + char getChar(String path); + + /** + * Returns the value of a <code>double</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>double</code> value of the specified property. + * @see #get(String) + */ + double getDouble(String path); + + /** + * Returns the value of a <code>float</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>float</code> value of the specified property. + * @see #get(String) + */ + float getFloat(String path); + + /** + * Returns the value of a <code>int</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>int</code> value of the specified property. + * @see #get(String) + */ + int getInt(String path); + + /** + * Returns the value of a <code>long</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>long</code> value of the specified property. + * @see #get(String) + */ + long getLong(String path); + + /** + * Returns the value of a <code>short</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>short</code> value of the specified property. + * @see #get(String) + */ + short getShort(String path); + + /** + * Returns the value of a <code>byte[]</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>byte[]</code> value of the specified property. + * @see #get(String) + */ + byte[] getBytes(String path); + + /** + * Returns the value of a <code>BigDecimal</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>BigDecimal</code> value of the specified property. + * @see #get(String) + */ + BigDecimal getBigDecimal(String path); + + /** + * Returns the value of a <code>BigInteger</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>BigInteger</code> value of the specified property. + * @see #get(String) + */ + BigInteger getBigInteger(String path); + + /** + * Returns the value of a <code>DataObject</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>DataObject</code> value of the specified property. + * @see #get(String) + */ + DataObject getDataObject(String path); + + /** + * Returns the value of a <code>Date</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>Date</code> value of the specified property. + * @see #get(String) + */ + Date getDate(String path); + + /** + * Returns the value of a <code>String</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>String</code> value of the specified property. + * @see #get(String) + */ + String getString(String path); + + /** + * Returns the value of a <code>List</code> property identified by the specified path. + * @param path the path to a valid object and property. + * @return the <code>List</code> value of the specified property. + * @see #get(String) + */ + List getList(String path); + + /** + * @see #getSequence() + * Returns the value of a <code>Sequence</code> property identified by the specified path. + * An implementation may throw an UnsupportedOperationException. + * @param path the path to a valid object and property. + * @return the <code>Sequence</code> value of the specified property. + * @see #get(String) + * @deprecated in 2.1.0. + */ + Sequence getSequence(String path); + + /** + * Sets the value of a <code>boolean</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setBoolean(String path, boolean value); + + /** + * Sets the value of a <code>byte</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setByte(String path, byte value); + + /** + * Sets the value of a <code>char</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setChar(String path, char value); + + /** + * Sets the value of a <code>double</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setDouble(String path, double value); + + /** + * Sets the value of a <code>float</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setFloat(String path, float value); + + /** + * Sets the value of a <code>int</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setInt(String path, int value); + + /** + * Sets the value of a <code>long</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setLong(String path, long value); + + /** + * Sets the value of a <code>short</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setShort(String path, short value); + + /** + * Sets the value of a <code>byte[]</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setBytes(String path, byte[] value); + + /** + * Sets the value of a <code>BigDecimal</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setBigDecimal(String path, BigDecimal value); + + /** + * Sets the value of a <code>BigInteger</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setBigInteger(String path, BigInteger value); + + /** + * Sets the value of a <code>DataObject</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setDataObject(String path, DataObject value); + + /** + * Sets the value of a <code>Date</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setDate(String path, Date value); + + /** + * Sets the value of a <code>String</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + */ + void setString(String path, String value); + + /** + * Sets the value of a <code>List</code> property identified by the specified path, to the specified value. + * @param path the path to a valid object and property. + * @param value the new value for the property. + * @see #set(String, Object) + * @see #setList(Property, List) + */ + void setList(String path, List value); + + /** + * Returns the value of the property at the specified index in {@link Type#getProperties property list} + * of this object's {@link Type type}. + * @param propertyIndex the index of the property. + * @return the value of the specified property. + * @see #get(Property) + */ + Object get(int propertyIndex); + + /** + * Sets the property at the specified index in {@link Type#getProperties property list} of this object's + * {@link Type type}, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void set(int propertyIndex, Object value); + + /** + * Returns whether the the property at the specified index in {@link Type#getProperties property list} of this object's + * {@link Type type}, is considered to be set. + * @param propertyIndex the index of the property. + * @return whether the specified property is set. + * @see #isSet(Property) + */ + boolean isSet(int propertyIndex); + + /** + * Unsets the property at the specified index in {@link Type#getProperties property list} of this object's {@link Type type}. + * @param propertyIndex the index of the property. + * @see #unset(Property) + */ + void unset(int propertyIndex); + + /** + * Returns the value of a <code>boolean</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>boolean</code> value of the specified property. + * @see #get(int) + */ + boolean getBoolean(int propertyIndex); + + /** + * Returns the value of a <code>byte</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>byte</code> value of the specified property. + * @see #get(int) + */ + byte getByte(int propertyIndex); + + /** + * Returns the value of a <code>char</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>char</code> value of the specified property. + * @see #get(int) + */ + char getChar(int propertyIndex); + + /** + * Returns the value of a <code>double</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>double</code> value of the specified property. + * @see #get(int) + */ + double getDouble(int propertyIndex); + + /** + * Returns the value of a <code>float</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>float</code> value of the specified property. + * @see #get(int) + */ + float getFloat(int propertyIndex); + + /** + * Returns the value of a <code>int</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>int</code> value of the specified property. + * @see #get(int) + */ + int getInt(int propertyIndex); + + /** + * Returns the value of a <code>long</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>long</code> value of the specified property. + * @see #get(int) + */ + long getLong(int propertyIndex); + + /** + * Returns the value of a <code>short</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>short</code> value of the specified property. + * @see #get(int) + */ + short getShort(int propertyIndex); + + /** + * Returns the value of a <code>byte[]</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>byte[]</code> value of the specified property. + * @see #get(int) + */ + byte[] getBytes(int propertyIndex); + + /** + * Returns the value of a <code>BigDecimal</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>BigDecimal</code> value of the specified property. + * @see #get(int) + */ + BigDecimal getBigDecimal(int propertyIndex); + + /** + * Returns the value of a <code>BigInteger</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>BigInteger</code> value of the specified property. + * @see #get(int) + */ + BigInteger getBigInteger(int propertyIndex); + + /** + * Returns the value of a <code>DataObject</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>DataObject</code> value of the specified property. + * @see #get(int) + */ + DataObject getDataObject(int propertyIndex); + + /** + * Returns the value of a <code>Date</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>Date</code> value of the specified property. + * @see #get(int) + */ + Date getDate(int propertyIndex); + + /** + * Returns the value of a <code>String</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>String</code> value of the specified property. + * @see #get(int) + */ + String getString(int propertyIndex); + + /** + * Returns the value of a <code>List</code> property identified by the specified property index. + * @param propertyIndex the index of the property. + * @return the <code>List</code> value of the specified property. + * @see #get(int) + */ + List getList(int propertyIndex); + + /** + * @see #getSequence() + * Returns the value of a <code>Sequence</code> property identified by the specified property index. + * An implementation may throw an UnsupportedOperationException. + * @param propertyIndex the index of the property. + * @return the <code>Sequence</code> value of the specified property. + * @see #get(int) + * @deprecated in 2.1.0. + */ + Sequence getSequence(int propertyIndex); + + /** + * Sets the value of a <code>boolean</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setBoolean(int propertyIndex, boolean value); + + /** + * Sets the value of a <code>byte</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setByte(int propertyIndex, byte value); + + /** + * Sets the value of a <code>char</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setChar(int propertyIndex, char value); + + /** + * Sets the value of a <code>double</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setDouble(int propertyIndex, double value); + + /** + * Sets the value of a <code>float</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setFloat(int propertyIndex, float value); + + /** + * Sets the value of a <code>int</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setInt(int propertyIndex, int value); + + /** + * Sets the value of a <code>long</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setLong(int propertyIndex, long value); + + /** + * Sets the value of a <code>short</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setShort(int propertyIndex, short value); + + /** + * Sets the value of a <code>byte[]</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setBytes(int propertyIndex, byte[] value); + + /** + * Sets the value of a <code>BigDecimal</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setBigDecimal(int propertyIndex, BigDecimal value); + + /** + * Sets the value of a <code>BigInteger</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setBigInteger(int propertyIndex, BigInteger value); + + /** + * Sets the value of a <code>DataObject</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setDataObject(int propertyIndex, DataObject value); + + /** + * Sets the value of a <code>Date</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setDate(int propertyIndex, Date value); + + /** + * Sets the value of a <code>String</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + */ + void setString(int propertyIndex, String value); + + /** + * Sets the value of a <code>List</code> property identified by the specified property index, to the specified value. + * @param propertyIndex the index of the property. + * @param value the new value for the property. + * @see #set(int, Object) + * @see #setList(Property, List) + */ + void setList(int propertyIndex, List value); + + /** + * Returns the value of the given property of this object. + * <p> + * If the property is {@link Property#isMany many-valued}, + * the result will be a {@link java.util.List} + * and each object in the List will be {@link Type#isInstance an instance of} + * the property's {@link Property#getType type}. + * Otherwise the result will directly be an instance of the property's type. + * @param property the property of the value to fetch. + * @return the value of the given property of the object. + * @see #set(Property, Object) + * @see #unset(Property) + * @see #isSet(Property) + */ + Object get(Property property); + + /** + * Sets the value of the given property of the object to the new value. + * <p> + * If the property is {@link Property#isMany many-valued}, + * the new value must be a {@link java.util.List} + * and each object in that list must be {@link Type#isInstance an instance of} + * the property's {@link Property#getType type}; + * the existing contents are cleared and the contents of the new value are added. + * Otherwise the new value directly must be an instance of the property's type + * and it becomes the new value of the property of the object. + * @param property the property of the value to set. + * @param value the new value for the property. + * @see #unset(Property) + * @see #isSet(Property) + * @see #get(Property) + */ + void set(Property property, Object value); + + /** + * Returns whether the property of the object is considered to be set. + * <p> + * isSet() for many-valued Properties returns true if the List is not empty and + * false if the List is empty. For single-valued Properties it returns true if the Property + * has been set() and not unset(), and false otherwise. + * Any call to set() without a call to unset() will cause isSet() to return true, regardless of + * the value being set. For example, after calling set(property, property.getDefault()) on a + * previously unset property, isSet(property) will return true, even though the value of + * get(property) will be unchanged. + * @param property the property in question. + * @return whether the property of the object is set. + * @see #set(Property, Object) + * @see #unset(Property) + * @see #get(Property) + */ + boolean isSet(Property property); + + /** + * Unsets the property of the object. + * <p> + * If the property is {@link Property#isMany many-valued}, + * the value must be an {@link java.util.List} + * and that list is cleared. + * Otherwise, + * the value of the property of the object + * is set to the property's {@link Property#getDefault default value}. + * The property will no longer be considered {@link #isSet set}. + * @param property the property in question. + * @see #isSet(Property) + * @see #set(Property, Object) + * @see #get(Property) + */ + void unset(Property property); + + /** + * Returns the value of the specified <code>boolean</code> property. + * @param property the property to get. + * @return the <code>boolean</code> value of the specified property. + * @see #get(Property) + */ + boolean getBoolean(Property property); + + /** + * Returns the value of the specified <code>byte</code> property. + * @param property the property to get. + * @return the <code>byte</code> value of the specified property. + * @see #get(Property) + */ + byte getByte(Property property); + + /** + * Returns the value of the specified <code>char</code> property. + * @param property the property to get. + * @return the <code>char</code> value of the specified property. + * @see #get(Property) + */ + char getChar(Property property); + + /** + * Returns the value of the specified <code>double</code> property. + * @param property the property to get. + * @return the <code>double</code> value of the specified property. + * @see #get(Property) + */ + double getDouble(Property property); + + /** + * Returns the value of the specified <code>float</code> property. + * @param property the property to get. + * @return the <code>float</code> value of the specified property. + * @see #get(Property) + */ + float getFloat(Property property); + + /** + * Returns the value of the specified <code>int</code> property. + * @param property the property to get. + * @return the <code>int</code> value of the specified property. + * @see #get(Property) + */ + int getInt(Property property); + + /** + * Returns the value of the specified <code>long</code> property. + * @param property the property to get. + * @return the <code>long</code> value of the specified property. + * @see #get(Property) + */ + long getLong(Property property); + + /** + * Returns the value of the specified <code>short</code> property. + * @param property the property to get. + * @return the <code>short</code> value of the specified property. + * @see #get(Property) + */ + short getShort(Property property); + + /** + * Returns the value of the specified <code>byte[]</code> property. + * @param property the property to get. + * @return the <code>byte[]</code> value of the specified property. + * @see #get(Property) + */ + byte[] getBytes(Property property); + + /** + * Returns the value of the specified <code>BigDecimal</code> property. + * @param property the property to get. + * @return the <code>BigDecimal</code> value of the specified property. + * @see #get(Property) + */ + BigDecimal getBigDecimal(Property property); + + /** + * Returns the value of the specified <code>BigInteger</code> property. + * @param property the property to get. + * @return the <code>BigInteger</code> value of the specified property. + * @see #get(Property) + */ + BigInteger getBigInteger(Property property); + + /** + * Returns the value of the specified <code>DataObject</code> property. + * @param property the property to get. + * @return the <code>DataObject</code> value of the specified property. + * @see #get(Property) + */ + DataObject getDataObject(Property property); + + /** + * Returns the value of the specified <code>Date</code> property. + * @param property the property to get. + * @return the <code>Date</code> value of the specified property. + * @see #get(Property) + */ + Date getDate(Property property); + + /** + * Returns the value of the specified <code>String</code> property. + * @param property the property to get. + * @return the <code>String</code> value of the specified property. + * @see #get(Property) + */ + String getString(Property property); + + /** + * Returns the value of the specified <code>List</code> property. + * The List returned contains the current values. + * Updates through the List interface operate on the current values of the DataObject. + * Each access returns the same List object. + * @param property the property to get. + * @return the <code>List</code> value of the specified property. + * @see #get(Property) + */ + List getList(Property property); + + /** + * @see #getSequence() + * Returns the value of the specified <code>Sequence</code> property. + * An implementation may throw an UnsupportedOperationException. + * @param property the property to get. + * @return the <code>Sequence</code> value of the specified property. + * @see #get(Property) + * @deprecated in 2.1.0. + */ + Sequence getSequence(Property property); + + /** + * Sets the value of the specified <code>boolean</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setBoolean(Property property, boolean value); + + /** + * Sets the value of the specified <code>byte</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setByte(Property property, byte value); + + /** + * Sets the value of the specified <code>char</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setChar(Property property, char value); + + /** + * Sets the value of the specified <code>double</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setDouble(Property property, double value); + + /** + * Sets the value of the specified <code>float</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setFloat(Property property, float value); + + /** + * Sets the value of the specified <code>int</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setInt(Property property, int value); + + /** + * Sets the value of the specified <code>long</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setLong(Property property, long value); + + /** + * Sets the value of the specified <code>short</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setShort(Property property, short value); + + /** + * Sets the value of the specified <code>byte[]</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setBytes(Property property, byte[] value); + + /** + * Sets the value of the specified <code>BigDecimal</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setBigDecimal(Property property, BigDecimal value); + + /** + * Sets the value of the specified <code>BigInteger</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setBigInteger(Property property, BigInteger value); + + /** + * Sets the value of the specified <code>DataObject</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setDataObject(Property property, DataObject value); + + /** + * Sets the value of the specified <code>Date</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setDate(Property property, Date value); + + /** + * Sets the value of the specified <code>String</code> property, to the specified value. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setString(Property property, String value); + + /** + * Sets the value of the specified <code>List</code> property, to the specified value. + * <p> The new value must be a {@link java.util.List} + * and each object in that list must be {@link Type#isInstance an instance of} + * the property's {@link Property#getType type}; + * the existing contents are cleared and the contents of the new value are added. + * @param property the property to set. + * @param value the new value for the property. + * @see #set(Property, Object) + */ + void setList(Property property, List value); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be a {@link Property#isContainment containment property}. + * The type of the created object is the {@link Property#getType declared type} of the specified property. + * @param propertyName the name of the specified containment property. + * @return the created data object. + * @see #createDataObject(String, String, String) + */ + DataObject createDataObject(String propertyName); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be a {@link Property#isContainment containment property}. + * The type of the created object is the {@link Property#getType declared type} of the specified property. + * @param propertyIndex the index of the specified containment property. + * @return the created data object. + * @see #createDataObject(int, String, String) + */ + DataObject createDataObject(int propertyIndex); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be a {@link Property#isContainment containment property}. + * The type of the created object is the {@link Property#getType declared type} of the specified property. + * @param property the specified containment property. + * @return the created data object. + * @see #createDataObject(Property, Type) + */ + DataObject createDataObject(Property property); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be a {@link Property#isContainment containment property}. + * The type of the created object is specified by the packageURI and typeName arguments. + * The specified type must be a compatible target for the property identified by propertyName. + * @param propertyName the name of the specified containment property. + * @param namespaceURI the namespace URI of the package containing the type of object to be created. + * @param typeName the name of a type in the specified package. + * @return the created data object. + * @see #createDataObject(String) + * @see DataGraph#getType + */ + DataObject createDataObject(String propertyName, String namespaceURI, String typeName); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be a {@link Property#isContainment containment property}. + * The type of the created object is specified by the packageURI and typeName arguments. + * The specified type must be a compatible target for the property identified by propertyIndex. + * @param propertyIndex the index of the specified containment property. + * @param namespaceURI the namespace URI of the package containing the type of object to be created. + * @param typeName the name of a type in the specified package. + * @return the created data object. + * @see #createDataObject(int) + * @see DataGraph#getType + */ + DataObject createDataObject(int propertyIndex, String namespaceURI, String typeName); + + /** + * Returns a new {@link DataObject data object} contained by this object using the specified property, + * which must be of {@link Property#isContainment containment type}. + * The type of the created object is specified by the type argument, + * which must be a compatible target for the speicifed property. + * @param property a containment property of this object. + * @param type the type of object to be created. + * @return the created data object. + * @see #createDataObject(int) + */ + DataObject createDataObject(Property property, Type type); + + /** + * Remove this object from its container and then unset all its non-{@link Property#isReadOnly readOnly} Properties. + * If this object is contained by a {@link Property#isReadOnly readOnly} {@link Property#isContainment containment property}, its non-{@link Property#isReadOnly readOnly} Properties will be unset but the object will not be removed from its container. + * All DataObjects recursively contained by {@link Property#isContainment containment Properties} will also be deleted. + */ + void delete(); + + /** + * Returns the containing {@link DataObject data object} + * or <code>null</code> if there is no container. + * @return the containing data object or <code>null</code>. + */ + DataObject getContainer(); + + /** + * Return the Property of the {@link DataObject data object} containing this data object + * or <code>null</code> if there is no container. + * @return the property containing this data object. + */ + Property getContainmentProperty(); + + /** + * Returns the {@link DataGraph data graph} for this object or <code>null</code> if there isn't one. + * @return the containing data graph or <code>null</code>. + */ + DataGraph getDataGraph(); + + /** + * Returns the data object's type. + * <p> + * The type defines the Properties available for reflective access. + * @return the type. + */ + Type getType(); + + /** + * Returns the <code>Sequence</code> for this DataObject. + * When getType().isSequencedType() == true, + * the Sequence of a DataObject corresponds to the + * XML elements representing the values of its Properties. + * Updates through DataObject and the Lists or Sequences returned + * from DataObject operate on the same data. + * When getType().isSequencedType() == false, null is returned. + * @return the <code>Sequence</code> or null. + */ + Sequence getSequence(); + + /** + * Returns a read-only List of the Properties currently used in this DataObject. + * This list will contain all of the Properties in getType().getProperties() + * and any Properties where isSet(property) is true. + * For example, Properties resulting from the use of + * open or mixed XML content are present if allowed by the Type. + * the List does not contain duplicates. + * The order of the Properties in the List begins with getType().getProperties() + * and the order of the remaining Properties is determined by the implementation. + * The same list will be returned unless the DataObject is updated so that + * the contents of the List change. + * @return the List of Properties currently used in this DataObject. + */ + List /* Property */ getInstanceProperties(); + + /** + * Returns the named Property from the current instance properties, + * or null if not found. The instance properties are getInstanceProperties(). + * @param propertyName the name of the Property + * @return the named Property from the DataObject's current instance properties, or null. + */ + Property getInstanceProperty(String propertyName); + + /** + * @deprecated replaced by {@link #getInstanceProperty(String)} in 2.1.0 + */ + Property getProperty(String propertyName); + + /** + * Returns the root {@link DataObject data object}. + * @return the root data object. + */ + DataObject getRootObject(); + + /** + * Returns the ChangeSummary with scope covering this dataObject, or null + * if there is no ChangeSummary. + * @return the ChangeSummary with scope covering this dataObject, or null. + */ + ChangeSummary getChangeSummary(); + + /** + * Removes this DataObject from its container, if any. + * Same as + * getContainer().getList(getContainmentProperty()).remove(this) or + * getContainer().unset(getContainmentProperty()) + * depending on getContainmentProperty().isMany() respectively. + */ + void detach(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Property.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Property.java new file mode 100644 index 0000000000..89a3857a75 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Property.java @@ -0,0 +1,115 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +import java.util.List; + +/** + * A representation of a Property in the {@link Type type} of a {@link DataObject data object}. + */ +public interface Property +{ + /** + * Returns the name of the Property. + * @return the Property name. + */ + String getName(); + + /** + * Returns the type of the Property. + * @return the Property type. + */ + Type getType(); + + /** + * Returns whether the Property is many-valued. + * @return <code>true</code> if the Property is many-valued. + */ + boolean isMany(); + + /** + * Returns whether the Property is containment, i.e., whether it represents by-value composition. + * @return <code>true</code> if the Property is containment. + */ + boolean isContainment(); + + /** + * Returns the containing type of this Property. + * @return the Property's containing type. + * @see Type#getProperties() + */ + Type getContainingType(); + + /** + * Returns the default value this Property will have in a {@link DataObject data object} where the Property hasn't been set. + * @return the default value. + */ + Object getDefault(); + + /** + * Returns true if values for this Property cannot be modified using the SDO APIs. + * When true, DataObject.set(Property property, Object value) throws an exception. + * Values may change due to other factors, such as services operating on DataObjects. + * @return true if values for this Property cannot be modified. + */ + boolean isReadOnly(); + + /** + * Returns the opposite Property if the Property is bi-directional or null otherwise. + * @return the opposite Property if the Property is bi-directional or null + */ + Property getOpposite(); + + /** + * Returns a list of alias names for this Property. + * @return a list of alias names for this Property. + */ + List /*String*/ getAliasNames(); + + /** + * Returns whether or not instances of this property can be set to null. The effect of calling set(null) on a non-nullable + * property is not specified by SDO. + * @return true if this property is nullable. + */ + boolean isNullable(); + + /** + * Returns whether or not this is an open content Property. + * @return true if this property is an open content Property. + */ + boolean isOpenContent(); + + /** + * Returns a read-only List of instance Properties available on this Property. + * <p> + * This list includes, at a minimum, any open content properties (extensions) added to + * the object before {@link commonj.sdo.helper.TypeHelper#define(DataObject) defining + * the Property's Type}. Implementations may, but are not required to in the 2.1 version + * of SDO, provide additional instance properties. + * @return the List of instance Properties on this Property. + */ + List /*Property*/ getInstanceProperties(); + + /** + * Returns the value of the specified instance property of this Property. + * @param property one of the properties returned by {@link #getInstanceProperties()}. + * @return the value of the specified property. + * @see DataObject#get(Property) + */ + Object get(Property property); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Sequence.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Sequence.java new file mode 100644 index 0000000000..d015633fa5 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Sequence.java @@ -0,0 +1,140 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +/** + * A sequence is a heterogeneous list of {@link Property properties} and corresponding values. + * It represents an ordered arbitrary mixture of data values from more than one property of a {@link DataObject data object}. + */ +public interface Sequence +{ + /** + * Returns the number of entries in the sequence. + * @return the number of entries. + */ + int size(); + + /** + * Returns the property for the given entry index. + * Returns <code>null</code> for mixed text entries. + * @param index the index of the entry. + * @return the property or <code>null</code> for the given entry index. + */ + Property getProperty(int index); + + /** + * Returns the property value for the given entry index. + * @param index the index of the entry. + * @return the value for the given entry index. + */ + Object getValue(int index); + + /** + * Sets the entry at a specified index to the new value. + * @param index the index of the entry. + * @param value the new value for the entry. + */ + Object setValue(int index, Object value); + + /** + * Adds a new entry with the specified property name and value + * to the end of the entries. + * @param propertyName the name of the entry's property. + * @param value the value for the entry. + */ + boolean add(String propertyName, Object value); + + /** + * Adds a new entry with the specified property index and value + * to the end of the entries. + * @param propertyIndex the index of the entry's property. + * @param value the value for the entry. + */ + boolean add(int propertyIndex, Object value); + + /** + * Adds a new entry with the specified property and value + * to the end of the entries. + * @param property the property of the entry. + * @param value the value for the entry. + */ + boolean add(Property property, Object value); + + /** + * Adds a new entry with the specified property name and value + * at the specified entry index. + * @param index the index at which to add the entry. + * @param propertyName the name of the entry's property. + * @param value the value for the entry. + */ + void add(int index, String propertyName, Object value); + + /** + * Adds a new entry with the specified property index and value + * at the specified entry index. + * @param index the index at which to add the entry. + * @param propertyIndex the index of the entry's property. + * @param value the value for the entry. + */ + void add(int index, int propertyIndex, Object value); + + /** + * Adds a new entry with the specified property and value + * at the specified entry index. + * @param index the index at which to add the entry. + * @param property the property of the entry. + * @param value the value for the entry. + */ + void add(int index, Property property, Object value); + + /** + * Removes the entry at the given entry index. + * @param index the index of the entry. + */ + void remove(int index); + + /** + * Moves the entry at <code>fromIndex</code> to <code>toIndex</code>. + * @param toIndex the index of the entry destination. + * @param fromIndex the index of the entry to move. + */ + void move(int toIndex, int fromIndex); + + /** + * @deprecated replaced by {@link #addText(String)} in 2.1.0 + */ + void add(String text); + + /** + * @deprecated replaced by {@link #addText(int, String)} in 2.1.0 + */ + void add(int index, String text); + + /** + * Adds a new text entry to the end of the Sequence. + * @param text value of the entry. + */ + void addText(String text); + + /** + * Adds a new text entry at the given index. + * @param index the index at which to add the entry. + * @param text value of the entry. + */ + void addText(int index, String text); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Type.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Type.java new file mode 100644 index 0000000000..c8d54a6ca0 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/Type.java @@ -0,0 +1,166 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo; + +import java.util.List; + +/** + * A representation of the type of a {@link Property property} of a {@link DataObject data object}. + */ +public interface Type +{ + /** + * Returns the name of the type. + * @return the type name. + */ + String getName(); + + /** + * Returns the namespace URI of the type. + * @return the namespace URI. + */ + String getURI(); + + /** + * Returns the Java class that this type represents. + * @return the Java class. + */ + Class getInstanceClass(); + + /** + * Returns whether the specified object is an instance of this type. + * @param object the object in question. + * @return <code>true</code> if the object is an instance. + * @see Class#isInstance + */ + boolean isInstance(Object object); + + /** + * Returns the List of the {@link Property Properties} of this type. + * <p> + * The expression + *<pre> + * type.getProperties().indexOf(property) + *</pre> + * yields the property's index relative to this type. + * As such, these expressions are equivalent: + *<pre> + * dataObject.{@link DataObject#get(int) get}(i) + * dataObject.{@link DataObject#get(Property) get}((Property)dataObject.getType().getProperties().get(i)); + *</pre> + * </p> + * @return the Properties of the type. + * @see Property#getContainingType + */ + List /*Property*/ getProperties(); + + /** + * Returns from {@link #getProperties all the Properties} of this type, the one with the specified name. + * As such, these expressions are equivalent: + *<pre> + * dataObject.{@link DataObject#get(String) get}("name") + * dataObject.{@link DataObject#get(Property) get}(dataObject.getType().getProperty("name")) + *</pre> + * </p> + * @return the Property with the specified name. + * @see #getProperties + */ + Property getProperty(String propertyName); + + /** + * Indicates if this Type specifies DataTypes (true) or DataObjects (false). + * When false, any object that is an instance of this type + * also implements the DataObject interface. + * True for simple types such as Strings and numbers. + * For any object: + * <pre> + * isInstance(object) && !isDataType() implies + * DataObject.class.isInstance(object) returns true. + * </pre> + * @return true if Type specifies DataTypes, false for DataObjects. + */ + boolean isDataType(); + + /** + * Indicates if this Type allows any form of open content. If false, + * dataObject.getInstanceProperties() must be the same as + * dataObject.getType().getProperties() for any DataObject dataObject of this Type. + * @return true if this Type allows open content. + */ + boolean isOpen(); + + /** + * Indicates if this Type specifies Sequenced DataObjects. + * Sequenced DataObjects are used when the order of values + * between Properties must be preserved. + * When true, a DataObject will return a Sequence. For example, + * <pre> + * Sequence elements = dataObject.{@link DataObject#getSequence() getSequence}(); + * </pre> + * @return true if this Type specifies Sequenced DataObjects. + */ + boolean isSequenced(); + + /** + * Indicates if this Type is abstract. If true, this Type cannot be + * instantiated. Abstract types cannot be used in DataObject or + * DataFactory create methods. + * @return true if this Type is abstract. + */ + boolean isAbstract(); + + /** + * Returns the List of base Types for this Type. The List is empty + * if there are no base Types. XSD <extension>, <restriction>, and + * Java extends keyword are mapped to this list. + * @return the List of base Types for this Type. + */ + List /*Type*/ getBaseTypes(); + + /** + * Returns the Properties declared in this Type as opposed to + * those declared in base Types. + * @return the Properties declared in this Type. + */ + List /*Property*/ getDeclaredProperties(); + + /** + * Return a list of alias names for this Type. + * @return a list of alias names for this Type. + */ + List /*String*/ getAliasNames(); + + /** + * Returns a read-only List of instance Properties available on this Type. + * <p> + * This list includes, at a minimum, any open content properties (extensions) added to + * the object before {@link commonj.sdo.helper.TypeHelper#define(DataObject) defining + * the Type's Type}. Implementations may, but are not required to in the 2.1 version + * of SDO, provide additional instance properties. + * @return the List of instance Properties on this Type. + */ + List /*Property*/ getInstanceProperties(); + + /** + * Returns the value of the specified instance property of this Type. + * @param property one of the properties returned by {@link #getInstanceProperties()}. + * @return the value of the specified property. + * @see DataObject#get(Property) + */ + Object get(Property property); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/CopyHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/CopyHelper.java new file mode 100644 index 0000000000..d185d4d420 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/CopyHelper.java @@ -0,0 +1,85 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import commonj.sdo.DataObject; +import commonj.sdo.impl.HelperProvider; + +/** + * A helper for copying DataObjects. + */ +public interface CopyHelper +{ + /** + * Create a shallow copy of the DataObject dataObject: + * Creates a new DataObject copiedDataObject with the same values + * as the source dataObject for each property where + * property.getType().isDataType() is true. + * The value of such a Property property in copiedDataObject is: + * dataObject.get(property) for single-valued Properties + * (copiedDataObject.get(property) equals() dataObject.get(property)), or + * a List where each member is equal to the member at the + * same index in dataObject for multi-valued Properties + * copiedDataObject.getList(property).get(i) equals() dataObject.getList(property).get(i) + * The copied Object is unset for each Property where + * property.getType().isDataType() is false + * since they are not copied. + * Read-only properties are copied. + * A copied object shares metadata with the source object + * sourceDO.getType() == copiedDO.getType() + * If a ChangeSummary is part of the source DataObject + * the copy has a new, empty ChangeSummary. + * Logging state is the same as the source ChangeSummary. + * + * @param dataObject to be copied + * @return copy of dataObject + */ + DataObject copyShallow(DataObject dataObject); + + /** + * Create a deep copy of the DataObject tree: + * Copies the dataObject and all its {@link commonj.sdo.Property#isContainment() contained} + * DataObjects recursively. + * Values of Properties are copied as in shallow copy, + * and values of Properties where + * property.getType().isDataType() is false + * are copied where each value copied must be a + * DataObject contained by the source dataObject. + * If a DataObject is outside the DataObject tree and the + * property is bidirectional, then the DataObject is skipped. + * If a DataObject is outside the DataObject tree and the + * property is unidirectional, then the same DataObject is referenced. + * Read-only properties are copied. + * If any DataObject referenced is not in the containment + * tree an IllegalArgumentException is thrown. + * If a ChangeSummary is part of the copy tree the new + * ChangeSummary refers to objects in the new DataObject tree. + * Logging state is the same as the source ChangeSummary. + * + * @param dataObject to be copied. + * @return copy of dataObject + * @throws IllegalArgumentException if any referenced DataObject + * is not part of the containment tree. + */ + DataObject copy(DataObject dataObject); + + /** + * The default CopyHelper. + */ + CopyHelper INSTANCE = HelperProvider.getCopyHelper(); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataFactory.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataFactory.java new file mode 100644 index 0000000000..8507b83440 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataFactory.java @@ -0,0 +1,64 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import commonj.sdo.DataObject; +import commonj.sdo.Type; +import commonj.sdo.impl.HelperProvider; + +/** + * A Factory for creating DataObjects. + * The created DataObjects are not connected to any other DataObjects. + */ +public interface DataFactory +{ + /** + * Create a DataObject of the Type specified by typeName with the given package uri. + * @param uri The uri of the Type. + * @param typeName The name of the Type. + * @return the created DataObject. + * @throws IllegalArgumentException if the uri and typeName does + * not correspond to a Type this factory can instantiate. + */ + DataObject create(String uri, String typeName); + + /** + * Create a DataObject supporting the given interface. + * InterfaceClass is the interface for the DataObject's Type. + * The DataObject created is an instance of the interfaceClass. + * @param interfaceClass is the interface for the DataObject's Type. + * @return the created DataObject. + * @throws IllegalArgumentException if the instanceClass does + * not correspond to a Type this factory can instantiate. + */ + DataObject create(Class interfaceClass); + + /** + * Create a DataObject of the Type specified. + * @param type The Type. + * @return the created DataObject. + * @throws IllegalArgumentException if the Type + * cannot be instantiaed by this factory. + */ + DataObject create(Type type); + + /** + * The default DataFactory. + */ + DataFactory INSTANCE = HelperProvider.getDataFactory(); + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataHelper.java new file mode 100644 index 0000000000..2b705c718e --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/DataHelper.java @@ -0,0 +1,215 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import java.util.Calendar; +import java.util.Date; +import java.util.Locale; + +import commonj.sdo.Type; +import commonj.sdo.Property; + +import commonj.sdo.impl.HelperProvider; + +/** + * Data helper methods. + */ +public interface DataHelper +{ + /** + * Convert from a String representation of an SDO date type to a Date. + * @param dateString the String representation of an SDO date type + * @return a Date representation of an SDO date type. + * @throws IllegalArgumentException for invalid formats. + */ + Date toDate(String dateString); + + /** + * Convert from a String representation of an SDO date type to a Calendar using the + * default locale. Same as toCalendar(dateString, null). + * @param dateString the String representation of an SDO date type + * @return a Calendar representation of an SDO date type. + * @throws IllegalArgumentException for invalid formats. + */ + Calendar toCalendar(String dateString); + + /** + * Convert from a String representation of an SDO date type to a Calendar using the + * specified locale, or the default locale if the locale is null. + * @param dateString the String representation of an SDO date type + * @param locale the locale or null for default locale. + * @return a Calendar representation of an SDO date type. + * @throws IllegalArgumentException for invalid formats. + */ + Calendar toCalendar(String dateString, Locale locale); + + /** + * Convert from a Date to a String representation of the DateTime type. + * @param date the date + * @return a Date to a String representation of the DateTime type. + */ + String toDateTime(Date date); + + /** + * Convert from a Date to a String representation of the Duration type. + * @param date the date + * @return a Date to a String representation of the Duration type. + */ + String toDuration(Date date); + + /** + * Convert from a Date to a String representation of the Time type. + * @param date the date + * @return a Date to a String representation of the Time type. + */ + String toTime(Date date); + + /** + * Convert from a Date to a String representation of the Day type. + * @param date the date + * @return a Date to a String representation of the Day type. + */ + String toDay(Date date); + + /** + * Convert from a Date to a String representation of the Month type. + * @param date the date + * @return a Date to a String representation of the Month type. + */ + String toMonth(Date date); + + /** + * Convert from a Date to a String representation of the MonthDay type. + * @param date the date + * @return a Date to a String representation of the MonthDay type. + */ + String toMonthDay(Date date); + + /** + * Convert from a Date to a String representation of the Year type. + * @param date the date + * @return a Date to a String representation of the Year type. + */ + String toYear(Date date); + + /** + * Convert from a Date to a String representation of the YearMonth type. + * @param date the date + * @return a Date to a String representation of the YearMonth type. + */ + String toYearMonth(Date date); + + /** + * Convert from a Date to a String representation of the YearMonthDay type. + * @param date the date + * @return a Date to a String representation of the YearMonthDay type. + */ + String toYearMonthDay(Date date); + + /** + * Convert from a Calendar to a String representation of the DateTime type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the DateTime type. + */ + String toDateTime(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the Duration type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the Duration type. + */ + String toDuration(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the Time type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the Time type. + */ + String toTime(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the Day type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the Day type. + */ + String toDay(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the Month type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the Month type. + */ + String toMonth(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the MonthDay type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the MonthDay type. + */ + String toMonthDay(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the Year type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the Year type. + */ + String toYear(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the YearMonth type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the YearMonth type. + */ + String toYearMonth(Calendar calendar); + + /** + * Convert from a Calendar to a String representation of the YearMonthDay type. + * @param calendar the calendar to convert + * @return a Calendar to a String representation of the YearMonthDay type. + */ + String toYearMonthDay(Calendar calendar); + + /** + * Convert the specified value to an {@link Type#getInstanceClass() instance} + * of the specified type. + * Supported conversions are listed in Section 16 of the SDO specification. + * @param type the target {@link Type#isDataType() data type}. + * @param value the value to convert + * @return a value of the specified type's instance class + * @throws IllegalArgumentException if the value could not be converted + * @see #convert(Property, Object) + */ + Object convert(Type type, Object value); + + /** + * Convert the specified value to an {@link Type#getInstanceClass() instance} + * of the specified property's {@link Property#getType() type}. + * The specified value must be a List if the property is {@link Property#isMany() + * many valued}. In this case, all the values in the List are converted. + * @param property the target {@link Type#isDataType() data type} property. + * @param value the value or List of values to convert + * @return a converted value or list of converted values + * @throws IllegalArgumentException if the value could not be converted + * @see #convert(Type, Object) + */ + Object convert(Property property, Object value); + + /** + * The default DataHelper. + */ + DataHelper INSTANCE = HelperProvider.getDataHelper(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/EqualityHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/EqualityHelper.java new file mode 100644 index 0000000000..31cd9b686f --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/EqualityHelper.java @@ -0,0 +1,92 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import commonj.sdo.DataObject; +import commonj.sdo.impl.HelperProvider; + +/** + * A helper for comparing DataObjects. + */ +public interface EqualityHelper +{ + /** + * <p>Two DataObjects are equalShallow if + * they have the same {@link DataObject#getType Type} + * and all their compared Properties are equal. + * The set of Properties compared are the + * {@link DataObject#getInstanceProperties() instance properties} + * where property.getType().isDataType() is true + * and property.getType() is not ChangeSummaryType. + * <br/>Two of these Property values are equal if they are both not + * {@link DataObject#isSet(Property) set}, or set to an equal value + * dataObject1.get(property).equals(dataObject2.get(property)) + * <br/>If the type is a sequenced type, the sequence entries must be the same. + * For each entry x in the sequence where the property is used in the comparison, + * dataObject1.getSequence().getValue(x).equals( + * dataObject2.getSequence().getValue(x)) and + * dataObject1.getSequence().getProperty(x) == + * dataObject2.getSequence().getProperty(x) + * must be true. + * </p> + * Returns true the objects have the same Type and all values of all compared Properties are equal. + * @param dataObject1 DataObject to be compared + * @param dataObject2 DataObject to be compared + * @return true the objects have the same Type and all values of all compared Properties are equal. + */ + boolean equalShallow(DataObject dataObject1, DataObject dataObject2); + + /** + * <p>Two DataObjects are equal(Deep) if they are equalShallow, + * all their compared Properties are equal, and all reachable DataObjects in their + * graphs excluding containers are equal. + * The set of Properties compared are the + * {@link DataObject#getInstanceProperties() instance properties} + * where property.getType().isDataType() is false, + * and is not a container property, ie !property.getOpposite().isContainment() + * <br/>Two of these Property values are equal if they are both not + * {@link DataObject#isSet(Property) set}, or all the DataObjects + * they refer to are {@link #equal(DataObject, DataObject) equal} in the + * context of dataObject1 and dataObject2. + * <br/>Note that properties to a containing DataObject are not compared + * which means two DataObject trees can be equal even if their containers are not equal. + * <br/>If the type is a sequenced type, the sequence entries must be the same. + * For each entry x in the sequence where the property is used in the comparison, + * equal(dataObject1.getSequence().getValue(x), + * dataObject2.getSequence().getValue(x)) and + * dataObject1.getSequence().getProperty(x) == + * dataObject2.getSequence().getProperty(x) + * must be true. + * </p><p> + * A DataObject directly or indirectly referenced by dataObject1 or dataObject2 + * can only be equal to exactly one DataObject directly or indirectly referenced + * by dataObject1 or dataObject2, respectively. + * This ensures that dataObject1 and dataObject2 are equal if the graph formed by + * all their referenced DataObjects have the same shape. + * </p> + * Returns true if the trees of DataObjects are equal(Deep). + * @param dataObject1 DataObject to be compared + * @param dataObject2 DataObject to be compared + * @return true if the trees of DataObjects are equal(Deep). + */ + boolean equal(DataObject dataObject1, DataObject dataObject2); + + /** + * The default EqualityHelper. + */ + EqualityHelper INSTANCE = HelperProvider.getEqualityHelper(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/HelperContext.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/HelperContext.java new file mode 100644 index 0000000000..058393f727 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/HelperContext.java @@ -0,0 +1,67 @@ +/**
+ * <copyright>
+ *
+ * Service Data Objects
+ * Version 2.1.0
+ * Licensed Materials
+ *
+ * (c) Copyright BEA Systems, Inc., International Business Machines Corporation,
+ * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG.,
+ * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies,
+ * 2005, 2006. All rights reserved.
+ *
+ * </copyright>
+ *
+ */
+
+package commonj.sdo.helper;
+
+/**
+ * This interface represents a helper execution context.
+ * The set of helpers returned by the methods in this interface have visibility
+ * to the same SDO metadata, that is, they execute in the same "scope".
+ */
+public interface HelperContext
+{
+ /**
+ * Gets the CopyHelper to use in this context.
+ * @return a CopyHelper object
+ */
+ CopyHelper getCopyHelper();
+
+ /**
+ * Gets the DataFactory to use in this context.
+ * @return a DataFactory object
+ */
+ DataFactory getDataFactory();
+
+ /**
+ * Gets the DataHelper to use in this context.
+ * @return a DataHelper object
+ */
+ DataHelper getDataHelper();
+
+ /**
+ * Gets the EqualityHelper to use in this context.
+ * @return an EqualityHelper object
+ */
+ EqualityHelper getEqualityHelper();
+
+ /**
+ * Gets the TypeHelper to use in this context.
+ * @return a TypeHelper object
+ */
+ TypeHelper getTypeHelper();
+
+ /**
+ * Gets the XMLHelper to use in this context.
+ * @return an XMLHelper object
+ */
+ XMLHelper getXMLHelper();
+
+ /**
+ * Gets the XSDHelper to use in this context.
+ * @return an XSDHelper object
+ */
+ XSDHelper getXSDHelper();
+}
diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/TypeHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/TypeHelper.java new file mode 100644 index 0000000000..6281a257b1 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/TypeHelper.java @@ -0,0 +1,96 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import java.util.List; + +import commonj.sdo.DataObject; +import commonj.sdo.Property; +import commonj.sdo.Type; +import commonj.sdo.impl.HelperProvider; + +/** + * Look up a Type given the uri and typeName or interfaceClass. + * SDO Types are available through the + * getType("commonj.sdo", typeName) method. + * Defines Types from DataObjects. + */ +public interface TypeHelper +{ + /** + * Return the Type specified by typeName with the given uri, + * or null if not found. + * @param uri The uri of the Type - type.getURI(); + * @param typeName The name of the Type - type.getName(); + * @return the Type specified by typeName with the given uri, + * or null if not found. + */ + Type getType(String uri, String typeName); + + /** + * Return the Type for this interfaceClass or null if not found. + * @param interfaceClass is the interface for the DataObject's Type - + * type.getInstanceClass(); + * @return the Type for this interfaceClass or null if not found. + */ + Type getType(Class interfaceClass); + + /** + * Get the open content (global) Property with the specified uri and name, or null + * if not found. + * @param uri the namespace URI of the open content Property. + * @param propertyName the name of the open content Property. + * @return the global Property. + */ + Property getOpenContentProperty(String uri, String propertyName); + + /** + * Define the DataObject as a Type. + * The Type is available through TypeHelper and DataGraph getType() methods. + * @param type the DataObject representing the Type. + * @return the defined Type. + * @throws IllegalArgumentException if the Type could not be defined. + */ + Type define(DataObject type); + + /** + * Define the list of DataObjects as Types. + * The Types are available through TypeHelper and DataGraph getType() methods. + * @param types a List of DataObjects representing the Types. + * @return the defined Types. + * @throws IllegalArgumentException if the Types could not be defined. + */ + List /*Type*/ define(List /*DataObject*/ types); + + /** + * Define the DataObject as a Property for setting open content. + * The containing Type of the open content property is not specified by SDO. + * If the specified uri is not null the defined property is accessible through + * TypeHelper.getOpenContentProperty(uri, propertyName). + * If a null uri is specified, the location and management of the open content property + * is not specified by SDO. + * @param uri the namespace URI of the open content Property or null. + * @return the defined open content Property. + * @throws IllegalArgumentException if the Property could not be defined. + */ + Property defineOpenContentProperty(String uri, DataObject property); + + /** + * The default TypeHelper. + */ + TypeHelper INSTANCE = HelperProvider.getTypeHelper(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLDocument.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLDocument.java new file mode 100644 index 0000000000..a89ff7bd9d --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLDocument.java @@ -0,0 +1,155 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import commonj.sdo.DataObject; + +/** + * Represents an XML Document containing a tree of DataObjects. + * + * An example XMLDocument fragment is: + * <?xml version="1.0"?> + * <purchaseOrder orderDate="1999-10-20"> + * + * created from this XML Schema fragment: + * <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> + * <xsd:element name="purchaseOrder" type="PurchaseOrderType"/> + * <xsd:complexType name="PurchaseOrderType"> + * + * Upon loading this XMLDocument: + * DataObject is an instance of Type PurchaseOrderType. + * RootElementURI is null because the XSD has no targetNamespace URI. + * RootElementName is purchaseOrder. + * Encoding is null because the document did not specify an encoding. + * XMLDeclaration is true because the document contained an XML declaration. + * XMLVersion is 1.0 + * SchemaLocation and noNamespaceSchemaLocation are null because they are + * not specified in the document. + * + * When saving the root element, if the type of the root dataObject is not the + * type of global element specified by rootElementURI and rootElementName, + * or if a global element does not exist for rootElementURI and rootElementName, + * then an xsi:type declaration is written to record the root DataObject's Type. + * + * When loading the root element and an xsi:type declaration is found + * it is used as the type of the root DataObject. In this case, + * if validation is not being performed, it is not an error if the + * rootElementName is not a global element. + */ +public interface XMLDocument +{ + /** + * Return the root DataObject for the XMLDocument. + * @return root DataObject for the XMLDocument. + */ + DataObject getRootObject(); + + /** + * Return the targetNamespace URI for the root element. + * If there is no targetNamespace URI, the value is null. + * The root element is a global element of the XML Schema + * with a type compatible to the DataObject. + * @return the targetNamespace URI for the root element. + */ + String getRootElementURI(); + + /** + * Return the name of the root element. + * The root element is a global element of the XML Schema + * with a type compatible to the DataObject. + * @return the name of the root element. + */ + String getRootElementName(); + + /** + * Return the XML encoding of the document, or null if not specified. + * The default value is "UTF-8". + * Specification of other values is implementation-dependent. + * @return the XML encoding of the document, or null if not specified. + */ + String getEncoding(); + + /** + * Set the XML encoding of the document, or null if not specified. + * @param encoding + */ + void setEncoding(String encoding); + + /** + * Return the XML declaration of the document. If true, + * XMLHelper save() will produce a declaration of the form: + * <?xml version="1.0" encoding="UTF-8"?> + * Encoding will be suppressed if getEncoding() is null. + * The default value is true. + * @return the XML declaration of the document. + */ + boolean isXMLDeclaration(); + + /** + * Set the XML declaration version of the document. + * @param xmlDeclaration the XML declaration version of the document. + */ + void setXMLDeclaration(boolean xmlDeclaration); + + /** + * Return the XML version of the document, or null if not specified. + * The default value is "1.0". + * Specification of other values is implementation-dependent. + * @return the XML version of the document, or null if not specified. + */ + String getXMLVersion(); + + /** + * Set the XML version of the document, or null if not specified. + * @param xmlVersion the XML version of the document, or null if not specified. + */ + void setXMLVersion(String xmlVersion); + + /** + * Return the value of the schemaLocation declaration + * for the http://www.w3.org/2001/XMLSchema-instance namespace in the + * root element, or null if not present. + * @return the value of the schemaLocation declaration, + * or null if not present. + */ + String getSchemaLocation(); + + /** + * Sets the value of the schemaLocation declaration + * for the http://www.w3.org/2001/XMLSchema-instance namespace in the + * root element, or null if it should not be present. + * @param schemaLocation the value of the schemaLocation declaration, or null. + */ + void setSchemaLocation(String schemaLocation); + + /** + * Return the value of the noNamespaceSchemaLocation declaration + * for the http://www.w3.org/2001/XMLSchema-instance namespace in the + * root element, or null if not present. + * @return the value of the noNamespaceSchemaLocation declaration, + * or null if not present. + */ + String getNoNamespaceSchemaLocation(); + + /** + * Sets the value of the noNamespaceSchemaLocation declaration + * for the http://www.w3.org/2001/XMLSchema-instance namespace in the + * root element, or null if it should not be present. + * @param schemaLocation the value of the noNamespaceSchemaLocation declaration, or null. + */ + void setNoNamespaceSchemaLocation(String schemaLocation); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLHelper.java new file mode 100644 index 0000000000..d28b017b41 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XMLHelper.java @@ -0,0 +1,201 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.io.Reader; +import java.io.Writer; +import javax.xml.transform.Source; +import javax.xml.transform.Result; + +import commonj.sdo.DataObject; +import commonj.sdo.impl.HelperProvider; + +/** + * A helper to convert XML documents into DataObects and + * DataObjects into XML documnets. + */ +public interface XMLHelper +{ + /** + * Creates and returns an XMLDocument from the input String. + * By default does not perform XSD validation. + * Same as + * load(new StringReader(inputString), null, null); + * + * @param inputString specifies the String to read from + * @return the new XMLDocument loaded + * @throws RuntimeException for errors in XML parsing or + * implementation-specific validation. + */ + XMLDocument load(String inputString); + + /** + * Creates and returns an XMLDocument from the inputStream. + * The InputStream will be closed after reading. + * By default does not perform XSD validation. + * Same as + * load(inputStream, null, null); + * + * @param inputStream specifies the InputStream to read from + * @return the new XMLDocument loaded + * @throws IOException for stream exceptions. + * @throws RuntimeException for errors in XML parsing or + * implementation-specific validation. + */ + XMLDocument load(InputStream inputStream) throws IOException; + + /** + * Creates and returns an XMLDocument from the inputStream. + * The InputStream will be closed after reading. + * By default does not perform XSD validation. + * @param inputStream specifies the InputStream to read from + * @param locationURI specifies the URI of the document for relative schema locations + * @param options implementation-specific options. + * @return the new XMLDocument loaded + * @throws IOException for stream exceptions. + * @throws RuntimeException for errors in XML parsing or + * implementation-specific validation. + */ + XMLDocument load(InputStream inputStream, String locationURI, Object options) throws IOException; + + /** + * Creates and returns an XMLDocument from the inputReader. + * The InputStream will be closed after reading. + * By default does not perform XSD validation. + * @param inputReader specifies the Reader to read from + * @param locationURI specifies the URI of the document for relative schema locations + * @param options implementation-specific options. + * @return the new XMLDocument loaded + * @throws IOException for stream exceptions. + * @throws RuntimeException for errors in XML parsing or + * implementation-specific validation. + */ + XMLDocument load(Reader inputReader, String locationURI, Object options) throws IOException; + + /** + * Creates and returns an XMLDocument from the inputSource. + * The InputSource will be closed after reading. + * By default does not perform XSD validation. + * @param inputSource specifies the Source to read from + * @param locationURI specifies the URI of the document for relative schema locations + * @param options implementation-specific options. + * @return the new XMLDocument loaded + * @throws IOException for stream exceptions. + * @throws RuntimeException for errors in XML parsing or + * implementation-specific validation. + */ + XMLDocument load(Source inputSource, String locationURI, Object options) throws IOException; + + /** + * Returns the DataObject saved as an XML document with the specified root element. + * Same as + * StringWriter stringWriter = new StringWriter(); + * save(createDocument(dataObject, rootElementURI, rootElementName), + * stringWriter, null); + * stringWriter.toString(); + * + * @param dataObject specifies DataObject to be saved + * @param rootElementURI the Target Namespace URI of the root XML element + * @param rootElementName the Name of the root XML element + * @return the saved XML document as a string + * @throws IllegalArgumentException if the dataObject tree + * is not closed or has no container. + */ + String save(DataObject dataObject, String rootElementURI, String rootElementName); + + /** + * Saves the DataObject as an XML document with the specified root element. + * Same as + * save(createDocument(dataObject, rootElementURI, rootElementName), + * outputStream, null); + * + * @param dataObject specifies DataObject to be saved + * @param rootElementURI the Target Namespace URI of the root XML element + * @param rootElementName the Name of the root XML element + * @param outputStream specifies the OutputStream to write to. + * @throws IOException for stream exceptions. + * @throws IllegalArgumentException if the dataObject tree + * is not closed or has no container. + */ + void save(DataObject dataObject, String rootElementURI, String rootElementName, OutputStream outputStream) throws IOException; + + /** + * Serializes an XMLDocument as an XML document into the outputStream. + * If the DataObject's Type was defined by an XSD, the serialization + * will follow the XSD. + * Otherwise the serialization will follow the format as if an XSD + * were generated as defined by the SDO specification. + * The OutputStream will be flushed after writing. + * Does not perform validation to ensure compliance with an XSD. + * @param xmlDocument specifies XMLDocument to be saved + * @param outputStream specifies the OutputStream to write to. + * @param options implementation-specific options. + * @throws IOException for stream exceptions. + * @throws IllegalArgumentException if the dataObject tree + * is not closed or has no container. + */ + void save(XMLDocument xmlDocument, OutputStream outputStream, Object options) throws IOException; + + /** + * Serializes an XMLDocument as an XML document into the outputWriter. + * If the DataObject's Type was defined by an XSD, the serialization + * will follow the XSD. + * Otherwise the serialization will follow the format as if an XSD + * were generated as defined by the SDO specification. + * The OutputStream will be flushed after writing. + * Does not perform validation to ensure compliance with an XSD. + * @param xmlDocument specifies XMLDocument to be saved + * @param outputWriter specifies the Writer to write to. + * @param options implementation-specific options. + * @throws IOException for stream exceptions. + * @throws IllegalArgumentException if the dataObject tree + * is not closed or has no container. + */ + void save(XMLDocument xmlDocument, Writer outputWriter, Object options) throws IOException; + + /** + * Serializes an XMLDocument as an XML document into the outputResult in a + * serialization technology independent format (as specified in + * javax.xml.transform). + * The OutputResult will be flushed after writing. + * Does not perform validation to ensure compliance with an XSD. + * @param xmlDocument specifies XMLDocument to be saved + * @param outputResult specifies Result to be saved + * @param options implementation-specific options. + * @throws IOException for stream exceptions. + * @throws IllegalArgumentException if the dataObject tree + * is not closed or has no container. + */ + void save(XMLDocument xmlDocument, Result outputResult, Object options) throws IOException; + + /** + * Creates an XMLDocument with the specified XML rootElement for the DataObject. + * @param dataObject specifies DataObject to be saved + * @param rootElementURI the Target Namespace URI of the root XML element + * @param rootElementName the Name of the root XML element + * @return XMLDocument a new XMLDocument set with the specified parameters. + */ + XMLDocument createDocument(DataObject dataObject, String rootElementURI, String rootElementName); + + /** + * The default XMLHelper. + */ + XMLHelper INSTANCE = HelperProvider.getXMLHelper(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XSDHelper.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XSDHelper.java new file mode 100644 index 0000000000..af4f002690 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/helper/XSDHelper.java @@ -0,0 +1,196 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.helper; + +import java.io.InputStream; +import java.io.Reader; +import java.util.List; +import java.util.Map; + +import commonj.sdo.Property; +import commonj.sdo.Type; +import commonj.sdo.impl.HelperProvider; + +/** + * Provides access to additional information when the + * Type or Property is defined by an XML Schema (XSD). + * Methods return null/false otherwise or if the information is unavailable. + * Defines Types from an XSD. +*/ +public interface XSDHelper +{ + /** + * Returns the local name as declared in the XSD. + * @param type to return local name for. + * @return the local name as declared in the XSD. + */ + String getLocalName(Type type); + + /** + * Returns the local name as declared in the XSD. + * @param property to return local name for. + * @return the local name as declared in the XSD. + */ + String getLocalName(Property property); + + /** + * Returns the namespace URI as declared in the XSD. + * @param property to return namespace URI for. + * @return the namespace URI as declared in the XSD. + */ + String getNamespaceURI(Property property); + + /** + * Returns true if the property is declared as an attribute in the XSD. + * Returns false if not known or for advanced cases. + * It is possible for both isAttribute and isElement to return false + * but they will not both return true. + * @param property to identify if an attribute. + * @return true if the property is declared as an attribute in the XSD. + */ + boolean isAttribute(Property property); + + /** + * Returns true if the property is declared as an element in the XSD. + * Returns false if not known or for advanced cases. + * It is possible for both isAttribute and isElement to return false + * but they will not both return true. + * @param property to identify if an element. + * @return true if the property is declared as an element in the XSD. + */ + boolean isElement(Property property); + + /** + * Returns true if the Type is declared to contain mixed content. + * A DataObject's mixed content values are typically accessed via a Sequence. + * @param type to identify if mixed content. + * @return true if the Type is declared to contain mixed content. + */ + boolean isMixed(Type type); + + /** + * Indicates if this helper contains XSD information for the specified type. + * @param type the type. + * @return true if this helper contains XSD information for the specified type. + */ + boolean isXSD(Type type); + + /** + * Returns the Property defined by the named global element or attribute + * in the targetNamespace uri, or null if not found. + * @param uri The uri of the targetNamespace. + * @param propertyName The name of the global property. + * @param isElement is true for global elements, false for global attributes. + * @return the Property defined by the named global element or attribute + * in the targetNamespace uri, or null if not found. + */ + Property getGlobalProperty(String uri, String propertyName, boolean isElement); + + /** + * Return the appinfo declared for this Type and source. + * The appinfo start and end tags and content are returned. + * The xml namespace context is preserved in the appinfo element. + * If more than one appinfo with the same source is declared on the same + * Type their contents are concatenated. + * @param type the type with the appinfo declaration + * @param source the source of the appinfo declaration. + * @return the appinfo declared for this Type and source. + */ + String getAppinfo(Type type, String source); + + /** + * Return the content of the appinfo declared for this Property and source. + * If the property is defined by ref= the appinfo of the referenced + * element or attribute is included. + * The appinfo start and end tags and content are returned. + * The xml namespace context is preserved in the appinfo element. + * If more than one appinfo with the same source is declared on the same + * Type their contents are concatenated. + * @param property the Property with the appinfo declaration + * @param source the source of the appinfo declaration. + * @return the appinfo declared for this Property and source. + */ + String getAppinfo(Property property, String source); + + /** + * Define the XML Schema as Types. + * The Types are available through TypeHelper and DataGraph getType() methods. + * Same as define(new StringReader(xsd), null) + * @param xsd the XML Schema. + * @return the defined Types. + * @throws IllegalArgumentException if the Types could not be defined. + */ + List /*Type*/ define(String xsd); + + /** + * Define XML Schema as Types. + * The Types are available through TypeHelper and DataGraph getType() methods. + * @param xsdReader reader to an XML Schema. + * @param schemaLocation the URI of the location of the schema, used + * for processing relative imports and includes. May be null if not used. + * @return the defined Types. + * @throws IllegalArgumentException if the Types could not be defined. + */ + List /*Type*/ define(Reader xsdReader, String schemaLocation); + + /** + * Define XML Schema as Types. + * The Types are available through TypeHelper and DataGraph getType() methods. + * @param xsdInputStream input stream to an XML Schema. + * @param schemaLocation the URI of the location of the schema, used + * for processing relative imports and includes. May be null if not used. + * @return the defined Types. + * @throws IllegalArgumentException if the Types could not be defined. + */ + List /*Type*/ define(InputStream xsdInputStream, String schemaLocation); + + /** + * Generate an XML Schema Declaration (XSD) from Types. + * Same as generate(types, null); + * @param types a List containing the Types + * @return a String containing the generated XSD. + * @throws IllegalArgumentException if the XSD could not be generated. + */ + String generate(List /*Type*/ types); + + /** + * Generate an XML Schema Declaration (XSD) from Types. + * Round trip from SDO to XSD to SDO is supported. + * Round trip from XSD to SDO to XSD is not supported. + * Use the original schema if one exists instead of generating a new one, as + * the generated XSD validates a different set of documents than the original XSD. + * Generating an XSD does not affect the XSDHelper or the Types. + * The Types must all have the same URI. + * The result is a String containing the generated XSD. + * All Types referenced with the same URI will be generated in the XSD + * and the list will be expanded to include all types generated. + * Any Types referenced with other URIs will cause + * imports to be produced as appropriate. + * Imports will include a schemaLocation if a Map is provided with an entry + * of the form key=import target namespace, value=schemaLocation + * @param types a List containing the Types + * @param namespaceToSchemaLocation map of target namespace to schema locations or null + * @return a String containing the generated XSD. + * @throws IllegalArgumentException if the XSD could not be generated. + */ + String generate(List /*Type*/ types, Map /*String, String*/ namespaceToSchemaLocation); + + /** + * The default XSDHelper. + */ + XSDHelper INSTANCE = HelperProvider.getXSDHelper(); +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/ExternalizableDelegator.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/ExternalizableDelegator.java new file mode 100644 index 0000000000..03220a8a32 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/ExternalizableDelegator.java @@ -0,0 +1,90 @@ +/** + * <copyright> + * + * Service Data Objects + * Version 2.1.0 + * Licensed Materials + * + * (c) Copyright BEA Systems, Inc., International Business Machines Corporation, + * Oracle Corporation, Primeton Technologies Ltd., Rogue Wave Software, SAP AG., + * Software AG., Sun Microsystems, Sybase Inc., Xcalia, Zend Technologies, + * 2005, 2006. All rights reserved. + * + * </copyright> + * + */ + +package commonj.sdo.impl; + +import java.io.Externalizable; +import java.io.IOException; +import java.io.ObjectInput; +import java.io.ObjectOutput; +import java.io.ObjectStreamException; + +/** + * Delegates DataObject serialization while ensuring implementation independent + * java.io.Serialization. An implementation of DataObject + * returns an ExternalizableDelegator from its writeReplace() method. + * + * The root DataObject is the object returned from do.getRootObject() where + * do is the DataObject being serialized in a java.io.ObjectOutputStream. + * When do.getContainer() == null then do is a root object. + * + * The byte format for each DataObject in the stream is: + * [0] [path] [root] // when do is not a root object + * [1] [rootXML] // when do is a root object + * + * where: + * [0] is the byte 0, serialized using writeByte(0). + * [1] is the byte 1, serialized using writeByte(1). + * + * [path] is an SDO path expression from the root DataObject to the serialized + * DataObject such that root.getDataObject(path) == do. + * Serialized using writeUTF(path). + * + * [root] is the root object serialized using writeObject(root). + * + * [rootXML] is the GZip of the XML serialization of the root DataObject. + * The XML serialization is the same as + * XMLHelper.INSTANCE.save(root, "commonj.sdo", "dataObject", stream); + * where stream is a GZIPOutputStream, length is the number of bytes + * in the stream, and bytes are the contents of the stream. + * Serialized using writeInt(length), write(bytes). + * + */ +public class ExternalizableDelegator implements Externalizable +{ + public interface Resolvable extends Externalizable + { + Object readResolve() throws ObjectStreamException; + } + + static final long serialVersionUID = 1; + transient Resolvable delegate; + + public ExternalizableDelegator() + { + delegate = HelperProvider.createResolvable(); + } + + public ExternalizableDelegator(Object target) + { + delegate = HelperProvider.createResolvable(target); + } + + public void writeExternal(ObjectOutput out) throws IOException + { + delegate.writeExternal(out); + } + + public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException + { + delegate.readExternal(in); + } + + public Object readResolve() throws ObjectStreamException + { + return delegate.readResolve(); + } +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/HelperProvider.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/HelperProvider.java new file mode 100644 index 0000000000..b4753a0683 --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/HelperProvider.java @@ -0,0 +1,402 @@ +/** + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package commonj.sdo.impl; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.io.UnsupportedEncodingException; +import java.security.AccessController; +import java.security.PrivilegedAction; + +import commonj.sdo.helper.CopyHelper; +import commonj.sdo.helper.DataFactory; +import commonj.sdo.helper.DataHelper; +import commonj.sdo.helper.EqualityHelper; +import commonj.sdo.helper.HelperContext; +import commonj.sdo.helper.TypeHelper; +import commonj.sdo.helper.XMLHelper; +import commonj.sdo.helper.XSDHelper; + +/** + * A HelperProvider obtains specific default helpers and other + * implementation-specific objects used by a Java implementation of SDO. + * + * @version $Rev$ $Date$ + */ +public abstract class HelperProvider { + /** + * The default HelperProvider INSTANCE. This is located using the ClassLoader used + * to load the HelperProvider class itself and if no default implementation is available + * this field will be set to null. + */ + public static final HelperProvider INSTANCE; + + /** + * The name of the resource that is used for service location. + */ + public static final String SERVICE_RESOURCE_NAME = "META-INF/services/commonj.sdo.impl.HelperProvider"; + + /** + * The name of the system property that will be checked for an implementation name. + */ + public static final String PROPERTY_NAME = "commonj.sdo.impl.HelperProvider"; + + static { + // initialize the default instance using this class's classloader + // set to null if none could be located (implies no default implementation) + HelperProvider provider; + try { + provider = getInstance(HelperProvider.class.getClassLoader()); + } catch (NoHelperProviderException e) { + provider = null; + } + INSTANCE = provider; + } + + /** + * Locate and instantiate a HelperProvider. + * <p/> + * Attempt to locate a HelperProvider using first the Thread's current context classloader and then, + * if that is not set, not readable, or does not provide an implementation, using the classloader + * used to load the HelperProvider class itself. + * <p/> + * A new instance is returned for each sucessful invocation. + * + * @return an implementation of HelperProvider + * @throws NoHelperProviderException if no provider implementation was defined or it could not be instantiated + */ + public static HelperProvider getInstance() throws NoHelperProviderException { + String implName = getImplementationName(); + + ClassLoader cl = getContextClassLoader(); + if (cl != null) { + HelperProvider provider = loadImplementation(cl, implName); + if (provider != null) { + return provider; + } + } + + cl = HelperProvider.class.getClassLoader(); + HelperProvider provider = loadImplementation(cl, implName); + if (provider != null) { + return provider; + } + + throw new NoHelperProviderException(implName); + } + + + /** + * Locate and instantiate a HelperProvider using the supplied ClassLoader. + * <p/> + * The name of the implementation to use is determined by the value of the "commonj.sdo.impl.HelperProvider" + * system property. If this is not set or this code does not have permission to read it then the name + * will be retrieved from the META-INF/services/commonj.sdo.impl.HelperProvider resource as returned + * by the supplied classloader as described in the + * <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">JAR file specification</a>. + * <p/> + * A new instance is returned for each sucessful invocation. + * + * @param cl the classloader to use to locate and instantiate the implementation + * @return the specified implementation of HelperProvider + * @throws NoHelperProviderException if no provider implementation was defined or it could not be instantiated + */ + public static HelperProvider getInstance(ClassLoader cl) throws NoHelperProviderException { + String implName = getImplementationName(); + HelperProvider provider = loadImplementation(cl, implName); + if (provider == null) { + throw new NoHelperProviderException(implName); + } + return provider; + } + + private static ClassLoader getContextClassLoader() { + try { + return (ClassLoader)AccessController.doPrivileged(new PrivilegedAction() { + public Object run() { + return Thread.currentThread().getContextClassLoader(); + } + }); + } catch (SecurityException e) { + return null; + } + } + + private static HelperProvider loadImplementation(ClassLoader cl, String implName) throws NoHelperProviderException { + // if no name is requested, locate using the supplied classloader + if (implName == null) { + implName = getImplementationName(cl); + } + // no implementation to try, return null + if (implName == null) { + return null; + } + + // try an instantiate the implementation + try { + return (HelperProvider) cl.loadClass(implName).newInstance(); + } catch (InstantiationException e) { + throw new NoHelperProviderException(implName, e); + } catch (IllegalAccessException e) { + throw new NoHelperProviderException(implName, e); + } catch (ClassNotFoundException e) { + throw new NoHelperProviderException(implName, e); + } + } + + private static String getImplementationName() { + try { + return (String)AccessController.doPrivileged(new PrivilegedAction() { + public Object run() { + return System.getProperty(PROPERTY_NAME); + } + }); + } catch (SecurityException e) { + return null; + } + } + + private static String getImplementationName(ClassLoader cl) { + InputStream is = cl.getResourceAsStream(SERVICE_RESOURCE_NAME); + if (is == null) { + return null; + } + + InputStreamReader in; + try { + in = new InputStreamReader(is, "UTF-8"); + } catch (UnsupportedEncodingException e) { + throw new AssertionError("UTF-8 encoding not available"); + } + + try { + BufferedReader reader = new BufferedReader(in, 128); + try { + String line; + while ((line = reader.readLine()) != null) { + int i = line.indexOf('#'); + if (i != -1) { + line = line.substring(0, i); + } + line = line.trim(); + if (line.length() > 0) { + return line; + } + } + return null; + } finally { + reader.close(); + } + } catch (IOException e) { + throw new NoHelperProviderException(e); + } + } + + + /////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // implementation specific methods for users that don't want to use the default implementation + + /** + * Returns a CopyHelper obtained from this implementation. + * + * @return a CopyHelper obtained from this implementation + */ + public abstract CopyHelper copyHelper(); + + /** + * Returns a DataFactory obtained from this implementation. + * + * @return a DataFactory obtained from this implementation + */ + public abstract DataFactory dataFactory(); + + /** + * Returns a DataHelper obtained from this implementation. + * + * @return a DataHelper obtained from this implementation + */ + public abstract DataHelper dataHelper(); + + /** + * Returns a EqualityHelper obtained from this implementation. + * + * @return a EqualityHelper obtained from this implementation + */ + public abstract EqualityHelper equalityHelper(); + + /** + * Returns a TypeHelper obtained from this implementation. + * + * @return a TypeHelper obtained from this implementation + */ + public abstract TypeHelper typeHelper(); + + /** + * Returns a XMLHelper obtained from this implementation. + * + * @return a XMLHelper obtained from this implementation + */ + public abstract XMLHelper xmlHelper(); + + /** + * Returns a XSDHelper obtained from this implementation. + * + * @return a XSDHelper obtained from this implementation + */ + public abstract XSDHelper xsdHelper(); + + /** + * Create a Resolvable using this implementation + * + * @return a Resolvable created using this implementation + */ + public abstract ExternalizableDelegator.Resolvable resolvable(); + + /** + * Create a Resolvable using this implementation + * + * @param target the object to be resolved + * @return a Resolvable created using this implementation + */ + public abstract ExternalizableDelegator.Resolvable resolvable(Object target); + + + /////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // static helper methods required by the specification + + /** + * Returns a CopyHelper obtained from the default HelperProvider. + * + * @return a CopyHelper obtained from the default HelperProvider + */ + public static CopyHelper getCopyHelper() { + return INSTANCE.copyHelper(); + } + + /** + * Returns a DataFactory obtained from the default HelperProvider. + * + * @return a DataFactory obtained from the default HelperProvider + */ + public static DataFactory getDataFactory() { + return INSTANCE.dataFactory(); + } + + /** + * Returns a DataHelper obtained from the default HelperProvider. + * + * @return a DataHelper obtained from the default HelperProvider + */ + public static DataHelper getDataHelper() { + return INSTANCE.dataHelper(); + } + + /** + * Returns a EqualityHelper obtained from the default HelperProvider. + * + * @return a EqualityHelper obtained from the default HelperProvider + */ + public static EqualityHelper getEqualityHelper() { + return INSTANCE.equalityHelper(); + } + + /** + * Returns a TypeHelper obtained from the default HelperProvider. + * + * @return a TypeHelper obtained from the default HelperProvider + */ + public static TypeHelper getTypeHelper() { + return INSTANCE.typeHelper(); + } + + /** + * Returns a XMLHelper obtained from the default HelperProvider. + * + * @return a XMLHelper obtained from the default HelperProvider + */ + public static XMLHelper getXMLHelper() { + return INSTANCE.xmlHelper(); + } + + /** + * Returns a XSDHelper obtained from the default HelperProvider. + * + * @return a XSDHelper obtained from the default HelperProvider + */ + public static XSDHelper getXSDHelper() { + return INSTANCE.xsdHelper(); + } + + /** + * Create a Resolvable using the default HelperProvider + * + * @return a Resolvable created using the default HelperProvider + */ + public static ExternalizableDelegator.Resolvable createResolvable() { + return INSTANCE.resolvable(); + } + + /** + * Create a Resolvable using the default HelperProvider + * + * @param target the object to be resolved + * @return a Resolvable created using the default HelperProvider + */ + public static ExternalizableDelegator.Resolvable createResolvable(Object target) { + return INSTANCE.resolvable(target); + } + + //////////////////////////////////////////////////////////////////////////////////////////////////// + // New in SDO 2.1 + //////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Gets the default HelperContext + * @return a HelperContext object + */ + public static HelperContext getDefaultContext() + { + return INSTANCE.helperContext(); + } + + HelperContext helperContext() + { + return defaultContext; + } + +// static HelperContext defaultContext = new DefaultHelperContext(); +// TODO: Feed back to spec -- Tuscany SDO implementation specific to create a special implementation of HelperContext + protected static HelperContext defaultContext; + + static class DefaultHelperContext implements HelperContext + { + public CopyHelper getCopyHelper() { return INSTANCE.copyHelper(); } + public DataFactory getDataFactory() { return INSTANCE.dataFactory(); } + public DataHelper getDataHelper() { return INSTANCE.dataHelper(); } + public EqualityHelper getEqualityHelper() { return INSTANCE.equalityHelper(); } + public TypeHelper getTypeHelper() { return INSTANCE.typeHelper(); } + public XMLHelper getXMLHelper() { return INSTANCE.xmlHelper(); } + public XSDHelper getXSDHelper() { return INSTANCE.xsdHelper(); } + } + +} diff --git a/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/NoHelperProviderException.java b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/NoHelperProviderException.java new file mode 100644 index 0000000000..83f0b21e2e --- /dev/null +++ b/sdo-java/branches/sdo-1.0-incubating/sdo-api/src/main/java/commonj/sdo/impl/NoHelperProviderException.java @@ -0,0 +1,58 @@ +/** + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package commonj.sdo.impl; + +/** + * Exception indicating that a HelperProvider could not be located or instantiated. + * The message will be set to the name of the implementation class; a null value + * indicates that the name of the implementation could not be determined. + * The cause will be set to the Throwable that prevented the provider from being + * located or created. + * + * @version $Revision$ $Date$ + */ +public class NoHelperProviderException extends RuntimeException { + private static final long serialVersionUID = 727646133930924084L; + + public NoHelperProviderException() { + } + + public NoHelperProviderException(String message) { + super(message); + } + + public NoHelperProviderException(String message, Throwable cause) { + super(message, cause); + } + + public NoHelperProviderException(Throwable cause) { + super(cause); + } + + /** + * Return the name of the implementation class that could not be provided. + * + * @return the name of the implementation class; may be null if not known + */ + public String getImplementationName() { + return getMessage(); + } +} |