All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object
|
+----org.xmlmiddleware.xmldbms.maps.MapBase
|
+----org.xmlmiddleware.xmldbms.maps.XMLDBMSMap
XMLDBMSMap objects describe how XML documents are mapped to databases and vice versa. You can think of them as compiled versions of map documents, although they can be created from other sources as well, such as a map factory that creates an XMLDBMSMap object from a DTD.
Applications that use XML-DBMS to transfer data treat XMLDBMSMap objects as opaque objects. That is, they call a map factory to create an XMLDBMSMap object, then pass it to a data transfer class such as DOMToDBMS or DBMSToDOM, often without calling any methods on it.
There are a variety of map utilities that can be used to modify or perform operations with maps. Most of these are used by map factories. However, some of them may be used by applications, such as to serialize a map or initialize it with the metadata in a particular database.
For example, the following code creates a map from the sales.map map document.
// Instantiate a new map factory from a database connection
// and SAX parser.
factory = new MapFactory_MapDocument(parser);
// Create an XMLDBMSMap from sales.map.
map = factory.createMap(new InputSource(new FileReader("sales.map")));
XMLDBMSMap objects are actually a graph of related objects. This graph can be fairly complex and it is a good idea to familiarize yourself with all map objects before trying to use them. (With a lower case m, map object refers to any of the objects in the graph, such as an XMLDBMSMap, a ClassMap, or a ColumnMap.) One way to understand the graph is to look at the private variables in each map class.
The graph of objects contains two views of the mapping, one from the XML point of view (ClassMaps) and one from the database point of view (ClassTableMaps and PropertyTableMaps). This allows the map to be accessed based either on XML metadata (element type and attribute names) or database metadata (table and column names). The MapInverter utility constructs one view from the other.
The following classes are in the XML-centric view of the map:
ClassMap
PropertyMap
RelatedClassMap
InlineClassMap
The following classes are in the database-centric view of the map:
ClassTableMap
ColumnMap
PropertyTableMap
RelatedClassTableMap
The following classes are shared by both views:
XMLDBMSMap
Table
Column
Key
LinkInfo
OrderInfo
The inheritance hierarchy of map classes is as follows. This makes clear how how similar the XML-centric and database-centric views of the map are. For example, PropertyMap (XML-centric), ColumnMap (database-centric), and PropertyTableMap (database-centric) all inherit from PropertyMapBase, since all map properties.
XMLMiddlewareException
MapBase
XMLDBMSMap
ClassMapBase
ClassMap
InlineClassMap
PropertyMapBase
PropertyMap
ColumnMap
PropertyTableMap
RelatedMapBase
RelatedClassMap
RelatedClassTableMap
ClassTableMap
Table
Column
Key
LinkInfo
OrderInfo
Expressed as a tree, the graph looks roughly as follows. An ellipsis (...) is used to indicate that the graph continues. In many cases, there are multiple paths to the same object, which is not shown due to the tree representation. For example, the Column in a PropertyMap can also be reached through the Table in the parent ClassMap or the Table in the PropertyMap (if any).
XMLDBMSMap
ClassMap (hashtable of)
Table
Column (hashtable of)
Key (hashtables of)
Column (array of)
ClassMap... (for used class map, optional)
ClassMap... (for base class, optional)
PropertyMap (hashtables of)
Table... (optional)
Column
LinkInfo (optional)
Key...
Key...
OrderInfo (optional)
Column (optional)
RelatedClassMap (hashtable of)
ClassMap...
LinkInfo...
OrderInfo... (optional)
InlineClassMap (hashtable of)
PropertyMap... (hashtable of)
RelatedClassMap... (hashtable of)
InlineClassMap... (hashtable of)
OrderInfo... (optional)
ClassTableMap (hashtable of)
Table...
Table... (for base class, optional)
ColumnMap (hashtable of)
Column
OrderInfo... (optional)
PropertyTableMap (hashtable of)
Table...
Column...
LinkInfo...
OrderInfo... (optional)
RelatedClassTableMap (vector of)
ClassTableMap...
LinkInfo...
OrderInfo... (optional)
ElementInsertionMap...
ColumnMap...
PropertyTableMap...
RelatedClassTableMap...
ElementInsertionMap...
OrderInfo... (optional)
Map objects are created by factory methods. These occur in all map objects except XMLDBMSMap, which has a simple constructor. For example, the following code creates a LinkInfo object.
LinkInfo linkInfo = LinkInfo.create(parentKey, childKey);
In many cases, factory methods can also be found on the parent object. For example, the following code creates a ClassMap object from an XMLDBMSMap object:
classMap = map.createClassMap(null, "foo");
When the factory method is called on the parent, the child object is automatically added to the parent object. Furthermore, if a child object with the same name already exists, that object will be returned instead of creating a new object. Since objects are frequently used in multiple places -- for example, the same ClassMap can appear in an XMLDBMSMap and a RelatedClassMap -- this is useful, as the alternative would be to first check if the object exists, then create it if it doesn't. For example, the following code is equivalent to calling createClassMap on an XMLDBMSMap object:
classMap = map.getClassMap(null, "foo");
if (classMap == null)
{
classMap = ClassMap.create(null, "foo");
map.addClassMap(classMap);
}
The primary difference between creating an object on its parent and adding it to its parent is that an exception is thrown when attempting to add an object that already exists on the parent. This is useful when a map factory wants to make sure that the same object is not mapped or created twice. For example, the following code throws an error if the table already has a column named "bar":
column = Column.create("bar");
table.addColumn(column);
Properties in maps fall into three categories:
Fundamental properties are set when the map object is created. They cannot be modified, but can be retrieved with a getXxxx method. For example:
column = Column.create("foo");
columnName = column.getName();
Objects in collection properties are manipulated with methods similar to the following:
getXxxx(String name) // Returns an object with the specified name. Returns null if
// the value does not exist. Used by map utilities and data
// transfer classes.
getXxxxs() // Returns an Enumeration or Hashtable over all objects of a
// given type. Used by map utilities and data transfer classes.
createXxxx(Xxxx xxx) // Returns a single object with the specified name. The method
// first attempts to retrieve an existing object and, if one
// doesn't exist, creates a new one. Used only by map factories.
addXxxx(Xxxx xxxx) // Adds a new object to the collection. Throws an error if
// the value already exists. Used only by map factories.
removeXxxx(String name) // Removes an object with the specified name. Throws an error
// if the value does not exist. Used only by map factories.
removeAllXxxxs() // Removes all objects of a given type. Used by map factories.
Single-valued properties are manipulated with methods similar to the following:
getXxxx() // Returns the object value. Used by map factories and data
// transfer classes.
setXxxx(new value) // Sets the object value, overriding the old value. In many cases,
// the argument can be null, which removes the property value.
// Used only by map factories.
Note that all getXxxx methods are optimized to the extent possible. This is done to minimize the time it takes to retrieve map information when transferring data and usually means that the method is declared final and simply returns the value of a class variable. This (hopefully) allows the method to be inlined by a clever Java compiler. It also means that no error is returned when it is inappropriate to call the method. This occurs when the state is invalid, such as during map construction, or when the state is valid but technically does not allow the method to be called, such as when OrderInfo.getFixedOrderValue() is called but an order column is used. In such cases, the returned value is not guaranteed to be correct.
Some collection properties and some single-valued properties are required to have values; others are not. Because map factories frequently need an object before they have enough information to completely construct it -- for example, a RelatedClassMap might be constructed before the ClassMap it points to is fully constructed -- map objects can have invalid state.
This is legal during map construction, but causes undefined behavior when the map is used to transfer data. That is, the data transfer classes such as DBMSToDOM and DOMToDBMS assume that the map objects are valid.
Because of this, map factories must ensure that a map has valid state before they return it. (The only exception to this rule is database metadata. A map factory can return an XMLDBMSMap that has not been initialized with database metadata and allow the application to do this. In this case, it is the application's responsibility to ensure the map is in a valid state.)
Map factories can check whether a map has valid state by calling MapChecker.check(XMLDBMSMap). Whether this is necessary depends on the map factory. Some map factories keep track of map state themselves, others call MapChecker to check for them.
XMLDBMSMap()
addClassMap(ClassMap)
addClassTableMap(ClassTableMap)
addNamedFormatter(String, StringFormatter)
addNamespace(String, String)
addTable(Table)
checkMetadata()
createClassMap(String, String)
createClassMap(XMLName)
createClassTableMap(Table)
createTable(String, String, String, String)
emptyStringIsNull()
getClassMap(String)
getClassMap(String, String)
getClassMaps()
getClassTableMap(String, String, String, String)
getClassTableMap(Table)
getClassTableMaps()
getDefaultFormatter(int)
getDefaultFormatters()
getNamedFormatter(String)
getNamedFormatters()
getNamespacePrefix(String)
getNamespacePrefixes()
getNamespaceURI(String)
getNamespaceURIs()
getTable(String, String, String, String)
getTables()
removeAllClassMaps()
removeAllClassTableMaps()
removeAllNamedFormatters()
removeAllTables()
removeClassMap(String)
removeClassMap(String, String)
removeClassTableMap(String, String, String, String)
removeClassTableMap(Table)
removeNamedFormatter(String, StringFormatter)
removeNamespaceByPrefix(String)
removeNamespaceByURI(String)
removeNamespaces()
removeTable(String, String, String, String)
removeTable(Table)
resetDefaultFormatters()
setDefaultFormatter(int, StringFormatter)
setEmptyStringIsNull(boolean)
XMLDBMSMap
public XMLDBMSMap()
emptyStringIsNull
public final boolean emptyStringIsNull()
setEmptyStringIsNull
public void setEmptyStringIsNull(boolean flag)
getDefaultFormatter
public final StringFormatter getDefaultFormatter(int type)
This method returns an object that implements the org.xmlmiddleware.conversions.formatters.StringFormatter interface.
getDefaultFormatters
public final Hashtable getDefaultFormatters()
setDefaultFormatter
public void setDefaultFormatter(int type,
StringFormatter formatter)
The format object must be an object that implements the org.xmlmiddleware.conversions.formatters.StringFormatter interface.
resetDefaultFormatters
public void resetDefaultFormatters()
getNamedFormatter
public final StringFormatter getNamedFormatter(String name)
getNamedFormatters
public final Hashtable getNamedFormatters()
addNamedFormatter
public void addNamedFormatter(String name,
StringFormatter formatter) throws XMLMiddlewareException
removeNamedFormatter
public void removeNamedFormatter(String name,
StringFormatter formatter) throws XMLMiddlewareException
removeAllNamedFormatters
public void removeAllNamedFormatters()
getNamespaceURI
public final String getNamespaceURI(String prefix)
getNamespacePrefix
public final String getNamespacePrefix(String uri)
getNamespaceURIs
public final Hashtable getNamespaceURIs()
getNamespacePrefixes
public final Hashtable getNamespacePrefixes()
addNamespace
public void addNamespace(String prefix,
String uri) throws XMLMiddlewareException
removeNamespaceByPrefix
public void removeNamespaceByPrefix(String prefix) throws XMLMiddlewareException
removeNamespaceByURI
public void removeNamespaceByURI(String uri) throws XMLMiddlewareException
removeNamespaces
public void removeNamespaces()
getClassMap
public final ClassMap getClassMap(String uri,
String localName)
If the ClassMap for the element type uses another ClassMap (which might use yet another ClassMap, and so on), this method returns the last ClassMap in the chain. This is the ClassMap actually used to transfer data.
getClassMap
public final ClassMap getClassMap(String universalName)
If the ClassMap for the element type uses another ClassMap (which might use yet another ClassMap, and so on), this method returns the last ClassMap in the chain. This is the ClassMap actually used to transfer data.
getClassMaps
public final Enumeration getClassMaps()
createClassMap
public ClassMap createClassMap(String uri,
String localName)
If the element type has already been mapped, returns the existing ClassMap.
createClassMap
public ClassMap createClassMap(XMLName elementTypeName)
If the element type has already been mapped, returns the existing ClassMap.
addClassMap
public void addClassMap(ClassMap classMap) throws XMLMiddlewareException
removeClassMap
public void removeClassMap(String uri,
String localName) throws XMLMiddlewareException
removeClassMap
public void removeClassMap(String universalName) throws XMLMiddlewareException
removeAllClassMaps
public void removeAllClassMaps()
getClassTableMap
public final ClassTableMap getClassTableMap(String databaseName,
String catalogName,
String schemaName,
String tableName)
getClassTableMap
public final ClassTableMap getClassTableMap(Table table)
getClassTableMaps
public final Enumeration getClassTableMaps()
createClassTableMap
public ClassTableMap createClassTableMap(Table table)
If the table has already been mapped as a class table, returns the existing ClassTableMap.
addClassTableMap
public void addClassTableMap(ClassTableMap classTableMap) throws XMLMiddlewareException
removeClassTableMap
public void removeClassTableMap(String databaseName,
String catalogName,
String schemaName,
String tableName) throws XMLMiddlewareException
removeClassTableMap
public void removeClassTableMap(Table table) throws XMLMiddlewareException
removeAllClassTableMaps
public void removeAllClassTableMaps()
getTable
public final Table getTable(String databaseName,
String catalogName,
String schemaName,
String tableName)
getTables
public final Enumeration getTables()
createTable
public Table createTable(String databaseName,
String catalogName,
String schemaName,
String tableName)
If the table exists, returns the existing Table.
addTable
public void addTable(Table table) throws XMLMiddlewareException
removeTable
public void removeTable(String databaseName,
String catalogName,
String schemaName,
String tableName) throws XMLMiddlewareException
This method should be used carefully, as numerous other map objects point to Tables. Those objects should be deleted before this method is called.
removeTable
public void removeTable(Table table) throws XMLMiddlewareException
This method should be used carefully, as numerous other map objects point to Tables. Those objects should be deleted before this method is called.
removeAllTables
public void removeAllTables()
This method should be used carefully, as numerous other map objects point to Tables. Those objects should be deleted before this method is called.
checkMetadata
public Table checkMetadata()
If the returned value is non-null, it can be used to determine the column for which metadata has not been set.
All Packages Class Hierarchy This Package Previous Next Index