0. Main configuration file
<config>
<data-source class="oracle.jdbc.pool.OracleDataSource"
url="jdbc:oracle:thin:@127.0.0.1:1521:db102"
user="bookstore" password="bookstore">
</data-source>
<mappings>
<file name="./bin/resources/test-mappings.xml"/>
<annotated-type class="ru.pan.magpie.mocks.Review" />
<annotated-object class="ru.pan.magpie.proxies.PKG_TEST_MAPPINGS" />
</mappings>
</config>
data-source: oracle data-source which will be used for getting Connection instance object
for all database calls;
class: full class name, the class must implement javax.sql.DataSource interface;
url: database url;
user: database schema user name;
password: schema password.
mappings: references to the mappings configuration files and annotated classes;
file: mappings configuration file satisfied
http://oracle-magpie.sourceforge.net/magpie-mappings-1.0.dtd DTD;
annotated-type: java entity class to oracle object type mapping defined by annotations;
annotated-object: java interface to oracle object (package/type) mapping defined by annotations;
1. Type mappings
Entity class mapping
<class-mapping class="tutor.model.Customer" db-type="TCUSTOMER" owner="BOOKSTORE">
<field name="customerId" db-name="customerId" />
<field name="orders" db-name="orders"
element-class="tutor.model.Order" collection-merging="update"/>
<field name="registrationDate" db-name="registrationDate" />
<property-group name="cuttedCustomer" behavior="skip" default="false">
<property name="orders" group="cuttedOrder"/>
<property name="customerId"/>
</property-group>
</class-mapping>
class-mapping: a mapping of the java entity class to the oracle object type;
class: full class name, required;
db-type: oracle object type name, required;
owner: oracle schema name, type's owner, not required,
default value - data-source user schema;
Note: if the owner-schema is different from the default user schema, last must have SELECT privilege
on ALL_ARGUMENTS, ALL_TYPE_ATTRS, ALL_TYPES, ALL_COLL_TYPES system view dictionaries.
field: a mapping of the java class field to the oracle object type field,
java field must have well-defined public getter and setter;
name: java field name, required;
db-name: oracle object type field name, required;
element-class: collection element class name,
required for collection or array field, ignored otherwise;
collection-merging: collection merging mode when updating a field
instance in the back oracle to java object conversion, possible values:
"reload": an initial collection will be cleared
and filled with new values of the returned collection field;
"append": collection values of the returned field
will be added to the initial collection;
"update": initial collection values will
be updated by appropriate return field values.
Note: A java class field is allowed to map to an oracle object type field if there is exists a mapping
(class or value) between the fields types.
property-group: a set of class fields,
which can be used in procedure calls for an object "weight" restriction;
name: group name, required;
behavior: ("skip"|"pass") the group will be passed/skipped respectively, default - "pass";
default: ("true"|"false") "true" - fields will be used for
all procedure calls, if an other property-group isn't specified; default - "false";
property: a property group element;
name: java field name, required;
property-group: reference to the property-group
of the field class mapping which will be used recursive.
Value class mapping
<value-mapping class="java.lang.Boolean">
<sql-type name="NUMBER"
to-oracle-method="ru.pan.magpie.convert.standards.NumberConversions.booleanToBigDecimal"
from-oracle-method="ru.pan.magpie.convert.standards.NumberConversions.bigDecimalToBoolean" />
</value-mapping>
value-mapping: a mapping of the java value class to the oracle sql type;
class: full class name, required;
sql-type, name: sql type name, required;
to-oracle-method: user-defined
static method which convert the value class instance to a class
supported by jdbc for this sql type, method signature:
public static Object methodName(Object, Connection);
from-oracle-method: user-defined
static method which convert to the value class instance from the default used by jdbc
class for this sql type, method signature:
public static Object methodName(Object); ;
2. Predefined value type mappings table
The mappings defined in the default-mappings.xml configuration file
| Java class | SQL Data Type | Notes |
|---|---|---|
|
java.lang.String |
CHAR, VARCHAR2, CHARACTER, STRING, VARCHAR, LONG, CLOB, ROWID |
|
|
java.util.Date |
DATE,TIMESTAMP |
|
|
byte[] |
BLOB |
|
|
java.math.BigDecimal |
PLS_INTEGER, BINARY_INTEGER, NATURAL, NATURALN, POSITIVE, POSITIVEN, NUMBER, DEC, DECIMAL, NUMERIC, FLOAT, INT, SMALLINT, INTEGER, REAL |
|
|
java.math.BigInteger, byte, java.lang.Byte, java.lang.Short, short, int, java.lang.Integer, long, java.lang.Long, float, java.lang.Float, double, java.lang.Double |
NUMBER |
|
|
boolean, java.lang.Boolean |
NUMBER |
0-false, 1-true |
|
int, java.lang.Integer |
INTEGER, BINARY_INTEGER |
|
|
long, java.lang.Long |
INTEGER, LONG |
|
|
float, java.lang.Float |
BINARY_FLOAT |
|
|
double, java.lang.Double |
BINARY_DOUBLE |
<db-object object-is="package" class="tutor.proxies.PKG_BOOKS_API"
name="PKG_BOOKS_API" owner="BOOKSTORE" base-class="">
<procedure java-name="formatBookIsbns" db-name="formatBookIsbns"
in-group="" out-group="">
<return class="java.util.List" element-class="tutor.model.Customer" out-group=""/>
<argument position="0" class="java.util.List" db-name="books"
element-class="tutor.model.Book" collection-merging="reload"
in-group="" out-group=""/>
</procedure>
</db-object>
db-object: a mapping of the java interface proxy class to the oracle
object package stored procedures or oracle object type methods;
class: full interface class name, required;
name: oracle package/type name;
object-is: ("package" | "type") mapping type, "package" is default;
owner: oracle schema name, object's owner, not required,
default value - data-source user schema;
base-class: the entity class which mapped to this oracle object type,
required for object-is="type".
procedure: a mapping of the stored procedure to the java method;
java-name: java method name, required;
db-name: oracle procedure name, required;
in-group: for an object type mapping,
"in" fields group set name for the base class object instance (look
property-group element in class-mapping);
out-group: "out" fields group set name.
return: for the functions, a function result mapping;
class: result class name, required;
element-class: if the result is a collection or an array, the collection element class name;
out-group: "out" fields group set name for the result instance.
argument: a method argument mapping;
position: position in the java method signature, starts with 0, required;
class: java argument class, required;
db-name: stored procedure argument name, required;
in-group: argument "in" fields group set name;
out-group: argument "out" fields group set name;
element-class: if the argument is a collection or an array, the collection element class name;
collection-merging: for "OUT" collection or array arguments,
collection merging mode using in the updating an argument instance in the back oracle
to java object conversion, possible values:
"reload": an initial collection will be cleared
and filled with values of the returned collection argument;
"append": collection values of the returned argument
will be added to the initial collection;
"update": initial collection values will
be updated by the appropriate return argument values.
| XML element | Annotation |
|---|---|
|
class-mapping |
DBType |
|
class-mapping.class |
- |
|
class-mapping.db-type |
DBType.name() |
|
class-mapping.owner |
DBType.owner() |
|
field |
DBTypeField |
|
field.name |
- |
|
field.db-name |
DBTypeField.name() |
|
field.element-class |
DBTypeField.elementClass() |
|
field.collection-merging |
DBTypeField.collectionMerging() |
|
property-group |
- |
|
value-mapping |
- |
|
db-object |
DBObject |
|
db-object.class |
- |
|
db-object.name |
DBObject.name() |
|
db-object.object-is |
DBObject.type() |
|
db-object.owner |
DBObject.owner() |
|
db-object.base-class |
DBObject.baseClass() |
|
procedure |
DBProcedure |
|
procedure.java-name |
- |
|
procedure.db-name |
DBProcedure.name() |
|
procedure.in-group |
DBProcedure.inPropertyGroup() |
|
procedure.out-group |
DBProcedure.outPropertyGroup() |
|
return |
- |
|
return.class |
- |
|
return.element-class |
DBProcedure.returnElementClass() |
|
return.out-group |
DBProcedure.returnOutPropertyGroup() |
|
argument |
DBArgument |
|
argument.position |
- |
|
argument.class |
- |
|
argument |
DBArgument |
|
argument.db-name |
DBArgument.name() |
|
argument.in-group |
DBArgument.inPropertyGroup() |
|
argument.out-group |
DBArgument.outPropertyGroup() |
|
argument.element-class |
DBArgument.elementClass() |
|
argument.collection-merging |
DBArgument.collectionMerging() |