diff options
Diffstat (limited to 'sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/DataObject.java')
| -rw-r--r-- | sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/DataObject.java | 1121 |
1 files changed, 1121 insertions, 0 deletions
diff --git a/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/DataObject.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/DataObject.java new file mode 100644 index 0000000000..fb592fcf58 --- /dev/null +++ b/sdo-java/trunk/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(); +} |