Oracle-magpie documentation

Oracle-magpie documentation

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

3. Interface mappings



	<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.

4. Using annotations

Instead of xml configuration files it is possible to define type and interface mappings by means of the java annotations. In the table below you can see correspondence of xml elements to annotations.

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()

5. Library API

Oracle-magpie JavaDoc API reference