diff options
Diffstat (limited to 'sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper')
9 files changed, 1171 insertions, 0 deletions
diff --git a/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/CopyHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/CopyHelper.java new file mode 100644 index 0000000000..d185d4d420 --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/DataFactory.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/DataFactory.java new file mode 100644 index 0000000000..8507b83440 --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/DataHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/DataHelper.java new file mode 100644 index 0000000000..2b705c718e --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/EqualityHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/EqualityHelper.java new file mode 100644 index 0000000000..31cd9b686f --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/HelperContext.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/HelperContext.java new file mode 100644 index 0000000000..143b29de17 --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/TypeHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/TypeHelper.java new file mode 100644 index 0000000000..6281a257b1 --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/XMLDocument.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/XMLDocument.java new file mode 100644 index 0000000000..a89ff7bd9d --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/XMLHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/XMLHelper.java new file mode 100644 index 0000000000..d28b017b41 --- /dev/null +++ b/sdo-java/trunk/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/trunk/sdo-api/src/main/java/commonj/sdo/helper/XSDHelper.java b/sdo-java/trunk/sdo-api/src/main/java/commonj/sdo/helper/XSDHelper.java new file mode 100644 index 0000000000..af4f002690 --- /dev/null +++ b/sdo-java/trunk/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(); +} |