org.apache.ojb.broker.util
Class BrokerHelper

java.lang.Object
  org.apache.ojb.broker.util.BrokerHelper

public class BrokerHelper
extends Object

This class contains helper methods primarily used by the PersistenceBroker implementation (e.g. contains methods to assign the the values of 'autoincrement' fields).
Furthermore it was used to introduce new features related to PersistenceBroker - these new features and services (if they stand the test of time) will be moved to separate services in future.

Version:

$Id: BrokerHelper.java,v 1.1 2007-08-24 22:17:36 ewestfal Exp $

Author:

Armin Waibel

Field Summary

private PersistenceBrokerImpl	m_broker
static String	REPOSITORY_NAME_SEPARATOR
private Map	sqlSelectMap

Constructor Summary

BrokerHelper(PersistenceBrokerImpl broker)

Method Summary

boolean	assertValidPkForDelete(ClassDescriptor cld, Object obj) returns true if the primary key fields are valid for delete, else false.
boolean	assertValidPksForStore(FieldDescriptor[] fieldDescriptors, Object[] pkValues) returns true if the primary key fields are valid for store, else false.
static PBKey	crossCheckPBKey(PBKey key) Check if the user of the given PBKey was null, if so we try to get user/password from the jdbc-connection-descriptor matching the given PBKey.getAlias().
boolean	doesExist(ClassDescriptor cld, Identity oid, Object obj) TODO: This method should be moved to JdbcAccess before 1.1 release.
static PBKey	extractAllTokens(String name) splits up the name string and extract db url, user name and password and build a new PBKey instance - the token '#' is used to separate the substrings.
Object[]	extractValueArray(ValueContainer[] containers) Extract an value array of the given ValueContainer array.
ValueContainer[]	getAllRwValues(ClassDescriptor cld, Object obj) Returns an array containing values for all READ/WRITE attributes of the object based on the specified ClassDescriptor.
static Object[]	getCollectionArray(Object collectionOrArray) Returns an object array for Collection, array or ManageableCollection instances.
static Iterator	getCollectionIterator(Object collectionOrArray) Returns an Iterator instance for Collection, object Array or ManageableCollection instances.
Query	getCountQuery(Query aQuery) Build a Count-Query based on aQuery
ValueContainer[]	getKeyValues(ClassDescriptor cld, Identity oid) Return primary key values of given Identity object.
ValueContainer[]	getKeyValues(ClassDescriptor cld, Identity oid, boolean convertToSql) Return key Values of an Identity
ValueContainer[]	getKeyValues(ClassDescriptor cld, Object objectOrProxy) returns an Array with an Objects PK VALUES, with any java-to-sql FieldConversion applied.
ValueContainer[]	getKeyValues(ClassDescriptor cld, Object objectOrProxy, boolean convertToSql) Returns an Array with an Objects PK VALUES if convertToSql is true, any associated java-to-sql conversions are applied.
ValueContainer[]	getNonKeyRwValues(ClassDescriptor cld, Object obj) Returns an array containing values for all non PK field READ/WRITE attributes of the object based on the specified ClassDescriptor.
private Platform	getPlatform() answer the platform
private Query	getQueryByCriteriaCount(QueryByCriteria aQuery) Create a Count-Query for QueryByCriteria
private Query	getQueryBySqlCount(QueryBySQL aQuery) Create a Count-Query for QueryBySQL
private ClassDescriptor	getRealClassDescriptor(ClassDescriptor aCld, Object anObj) Answer the real ClassDescriptor for anObj ie.
private Query	getReportQueryByCriteriaCount(ReportQueryByCriteria aQuery) Create a Count-Query for ReportQueryByCriteria
ValueContainer[]	getValuesForObject(FieldDescriptor[] fields, Object obj, boolean convertToSql)
ValueContainer[]	getValuesForObject(FieldDescriptor[] fields, Object obj, boolean convertToSql, boolean assignAutoincrement) Get the values of the fields for an obj Autoincrement values are automatically set.
static boolean	hasAnonymousKeyReference(ClassDescriptor cld, ObjectReferenceDescriptor rds) Returns true if one or more anonymous FK fields are used.
boolean	hasNullPKField(ClassDescriptor cld, Object obj) Detect if the given object has a PK field represents a 'null' value.
void	link(Object obj, boolean insert) This method concatenate the main object with all reference objects (1:1, 1:n and m:n) by hand.
void	link(Object source, CollectionDescriptor cds, List referencesToLink) Link a bunch of 1:n or m:n objects.
void	link(Object source, CollectionDescriptor cds, Object referenceToLink) Link a single 1:n or m:n object.
void	link(Object obj, ObjectReferenceDescriptor ord, boolean insert) This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand.
boolean	link(Object obj, String attributeName, boolean insert) This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand.
boolean	link(Object obj, String attributeName, Object reference, boolean insert) This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand.
private void	linkOrUnlink(boolean doLink, Object obj, boolean insert)
private void	linkOrUnlink(boolean doLink, Object obj, ObjectReferenceDescriptor ord, boolean insert)
private boolean	linkOrUnlink(boolean doLink, Object obj, String attributeName, boolean insert)
private void	linkOrUnlinkOneToOne(boolean doLink, Object obj, ObjectReferenceDescriptor ord, boolean insert)
private void	linkOrUnlinkXToMany(boolean doLink, Object obj, CollectionDescriptor cod, boolean insert)
boolean	representsNull(FieldDescriptor fld, Object aValue) Decide if the given object value represents 'null'. - If given value is 'null' itself, true will be returned - If given value is instance of Number with value 0 and the field-descriptor represents a primitive field, true will be returned - If given value is instance of String with length 0 and the field-descriptor is a primary key, true will be returned
private Object	setAutoIncrementValue(FieldDescriptor fd, Object obj) Set an autoincremented value in given object field that has already had a field conversion run on it, if an value for the given field is already set, it will be overridden - no further checks are done.
void	unlink(Object obj) Unlink all references from this object.
void	unlink(Object source, CollectionDescriptor cds, List referencesToUnlink) Unlink a bunch of 1:n or m:n objects.
void	unlink(Object source, CollectionDescriptor cds, Object referenceToUnlink) Unlink a single 1:n or m:n object.
void	unlink(Object obj, ObjectReferenceDescriptor ord, boolean insert) Unlink the specified reference from this object.
boolean	unlink(Object source, String attributeName) Unlink all referenced objects of the specified field.
boolean	unlink(Object source, String attributeName, Object target) Unlink the specified reference object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REPOSITORY_NAME_SEPARATOR

public static final String REPOSITORY_NAME_SEPARATOR

See Also:

Constant Field Values

m_broker

private PersistenceBrokerImpl m_broker

sqlSelectMap

private Map sqlSelectMap

Constructor Detail

BrokerHelper

public BrokerHelper(PersistenceBrokerImpl broker)

Method Detail

extractAllTokens

public static PBKey extractAllTokens(String name)

splits up the name string and extract db url, user name and password and build a new PBKey instance - the token '#' is used to separate the substrings.

Throws:

PersistenceBrokerException - if given name was null

crossCheckPBKey

public static PBKey crossCheckPBKey(PBKey key)

Check if the user of the given PBKey was null, if so we try to get user/password from the jdbc-connection-descriptor matching the given PBKey.getAlias().

getRealClassDescriptor

private ClassDescriptor getRealClassDescriptor(ClassDescriptor aCld,
                                               Object anObj)

Answer the real ClassDescriptor for anObj ie. aCld may be an Interface of anObj, so the cld for anObj is returned

getKeyValues

public ValueContainer[] getKeyValues(ClassDescriptor cld,
                                     Object objectOrProxy,
                                     boolean convertToSql)
                              throws PersistenceBrokerException

Returns an Array with an Objects PK VALUES if convertToSql is true, any associated java-to-sql conversions are applied. If the Object is a Proxy or a VirtualProxy NO conversion is necessary.

Parameters:

objectOrProxy -

convertToSql -

Returns:

Object[]

Throws:

PersistenceBrokerException

getKeyValues

public ValueContainer[] getKeyValues(ClassDescriptor cld,
                                     Identity oid)
                              throws PersistenceBrokerException

Return primary key values of given Identity object.

Parameters:

cld -

oid -

Returns:

Object[]

Throws:

PersistenceBrokerException

getKeyValues

public ValueContainer[] getKeyValues(ClassDescriptor cld,
                                     Identity oid,
                                     boolean convertToSql)
                              throws PersistenceBrokerException

Return key Values of an Identity

Parameters:

cld -

oid -

convertToSql -

Returns:

Object[]

Throws:

PersistenceBrokerException

getKeyValues

public ValueContainer[] getKeyValues(ClassDescriptor cld,
                                     Object objectOrProxy)
                              throws PersistenceBrokerException

returns an Array with an Objects PK VALUES, with any java-to-sql FieldConversion applied. If the Object is a Proxy or a VirtualProxy NO conversion is necessary.

Parameters:

objectOrProxy -

Returns:

Object[]

Throws:

PersistenceBrokerException

representsNull

public boolean representsNull(FieldDescriptor fld,
                              Object aValue)

Decide if the given object value represents 'null'.
- If given value is 'null' itself, true will be returned
- If given value is instance of Number with value 0 and the field-descriptor represents a primitive field, true will be returned
- If given value is instance of String with length 0 and the field-descriptor is a primary key, true will be returned

hasNullPKField

public boolean hasNullPKField(ClassDescriptor cld,
                              Object obj)

Detect if the given object has a PK field represents a 'null' value.

setAutoIncrementValue

private Object setAutoIncrementValue(FieldDescriptor fd,
                                     Object obj)

Set an autoincremented value in given object field that has already had a field conversion run on it, if an value for the given field is already set, it will be overridden - no further checks are done.

The data type of the value that is returned by this method is compatible with the java-world. The return value has NOT been run through a field conversion and converted to a corresponding sql-type.

Returns:

the autoincremented value set on given object

Throws:

PersistenceBrokerException - if there is an erros accessing obj field values

getValuesForObject

public ValueContainer[] getValuesForObject(FieldDescriptor[] fields,
                                           Object obj,
                                           boolean convertToSql,
                                           boolean assignAutoincrement)
                                    throws PersistenceBrokerException

Get the values of the fields for an obj Autoincrement values are automatically set.

Parameters:

fields -

obj -

Throws:

PersistenceBrokerException

getValuesForObject

public ValueContainer[] getValuesForObject(FieldDescriptor[] fields,
                                           Object obj,
                                           boolean convertToSql)
                                    throws PersistenceBrokerException

Throws:

PersistenceBrokerException

getNonKeyRwValues

public ValueContainer[] getNonKeyRwValues(ClassDescriptor cld,
                                          Object obj)
                                   throws PersistenceBrokerException

Returns an array containing values for all non PK field READ/WRITE attributes of the object based on the specified ClassDescriptor.
NOTE: This method doesn't do any checks on the specified ClassDescriptor the caller is reponsible to pass a valid descriptor.

Parameters:

cld - The ClassDescriptor to extract the RW-fields

obj - The object with target fields to extract.

Throws:

MetadataException - if there is an erros accessing obj field values

PersistenceBrokerException

getAllRwValues

public ValueContainer[] getAllRwValues(ClassDescriptor cld,
                                       Object obj)
                                throws PersistenceBrokerException

Returns an array containing values for all READ/WRITE attributes of the object based on the specified ClassDescriptor.
NOTE: This method doesn't do any checks on the specified ClassDescriptor the caller is reponsible to pass a valid descriptor.

Parameters:

cld - The ClassDescriptor to extract the RW-fields

obj - The object with target fields to extract.

Throws:

MetadataException - if there is an erros accessing obj field values

PersistenceBrokerException

extractValueArray

public Object[] extractValueArray(ValueContainer[] containers)

Extract an value array of the given ValueContainer array.

Parameters:

containers -

Returns:

An object array

assertValidPksForStore

public boolean assertValidPksForStore(FieldDescriptor[] fieldDescriptors,
                                      Object[] pkValues)

returns true if the primary key fields are valid for store, else false. PK fields are valid if each of them is either an OJB managed attribute (autoincrement or locking) or if it contains a valid non-null value

Parameters:

fieldDescriptors - the array of PK fielddescriptors

pkValues - the array of PK values

Returns:

boolean

assertValidPkForDelete

public boolean assertValidPkForDelete(ClassDescriptor cld,
                                      Object obj)

returns true if the primary key fields are valid for delete, else false. PK fields are valid if each of them contains a valid non-null value

Parameters:

cld - the ClassDescriptor

obj - the object

Returns:

boolean

getCountQuery

public Query getCountQuery(Query aQuery)

Build a Count-Query based on aQuery

Parameters:

aQuery -

Returns:

The count query

getQueryBySqlCount

private Query getQueryBySqlCount(QueryBySQL aQuery)

Create a Count-Query for QueryBySQL

Parameters:

aQuery -

Returns:

The count query

getQueryByCriteriaCount

private Query getQueryByCriteriaCount(QueryByCriteria aQuery)

Create a Count-Query for QueryByCriteria

getReportQueryByCriteriaCount

private Query getReportQueryByCriteriaCount(ReportQueryByCriteria aQuery)

Create a Count-Query for ReportQueryByCriteria

getPlatform

private Platform getPlatform()

answer the platform

Returns:

the platform

doesExist

public boolean doesExist(ClassDescriptor cld,
                         Identity oid,
                         Object obj)

TODO: This method should be moved to JdbcAccess before 1.1 release. This method checks if the requested object can be found in database (without object materialization).

Parameters:

cld - The ClassDescriptor of the object/Identity to check.

obj - The object to check.

oid - The associated Identity. Identity of the object

Returns:

Return true if the object is already persisted, false if the object is transient.

link

public void link(Object obj,
                 boolean insert)

This method concatenate the main object with all reference objects (1:1, 1:n and m:n) by hand. This method is needed when in the reference metadata definitions the auto-xxx setting was disabled. More info see OJB doc.

unlink

public void unlink(Object obj)

Unlink all references from this object. More info see OJB doc.

Parameters:

obj - Object with reference

linkOrUnlink

private void linkOrUnlink(boolean doLink,
                          Object obj,
                          boolean insert)

link

public void link(Object obj,
                 ObjectReferenceDescriptor ord,
                 boolean insert)

This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand. This method is needed when in the reference metadata definitions the auto-xxx setting was disabled. More info see OJB doc.

Parameters:

obj - Object with reference

ord - the ObjectReferenceDescriptor of the reference

insert - flag signals insert operation

link

public boolean link(Object obj,
                    String attributeName,
                    boolean insert)

This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand. This method is needed when in the reference metadata definitions the auto-xxx setting was disabled. More info see OJB doc.

Parameters:

obj - Object with reference

attributeName - field name of the reference

insert - flag signals insert operation

Returns:

true if the specified reference was found and linking was successful

link

public boolean link(Object obj,
                    String attributeName,
                    Object reference,
                    boolean insert)

This method concatenate the main object and the specified reference object (1:1 reference a referenced object, 1:n and m:n reference a collection of referenced objects) by hand. This method is needed when in the reference metadata definitions the auto-xxx setting was disabled. More info see OJB doc.

Parameters:

obj - Object with reference

attributeName - field name of the reference

reference - The referenced object

insert - flag signals insert operation

Returns:

true if the specified reference was found and linking was successful

unlink

public boolean unlink(Object source,
                      String attributeName,
                      Object target)

Unlink the specified reference object. More info see OJB doc.

Parameters:

source - The source object with the specified reference field.

attributeName - The field name of the reference to unlink.

target - The referenced object to unlink.

unlink

public boolean unlink(Object source,
                      String attributeName)

Unlink all referenced objects of the specified field. More info see OJB doc.

Parameters:

source - The source object with the specified reference.

attributeName - The field name of the reference to unlink.

unlink

public void unlink(Object obj,
                   ObjectReferenceDescriptor ord,
                   boolean insert)

Unlink the specified reference from this object. More info see OJB doc.

Parameters:

obj - Object with reference

ord - the ObjectReferenceDescriptor of the reference

insert - flag signals insert operation

linkOrUnlink

private boolean linkOrUnlink(boolean doLink,
                             Object obj,
                             String attributeName,
                             boolean insert)

linkOrUnlink

private void linkOrUnlink(boolean doLink,
                          Object obj,
                          ObjectReferenceDescriptor ord,
                          boolean insert)

linkOrUnlinkXToMany

private void linkOrUnlinkXToMany(boolean doLink,
                                 Object obj,
                                 CollectionDescriptor cod,
                                 boolean insert)

linkOrUnlinkOneToOne

private void linkOrUnlinkOneToOne(boolean doLink,
                                  Object obj,
                                  ObjectReferenceDescriptor ord,
                                  boolean insert)

unlink

public void unlink(Object source,
                   CollectionDescriptor cds,
                   List referencesToUnlink)

Unlink a bunch of 1:n or m:n objects.

Parameters:

source - The source object with reference.

cds - The CollectionDescriptor of the relation.

referencesToUnlink - List of referenced objects to unlink.

unlink

public void unlink(Object source,
                   CollectionDescriptor cds,
                   Object referenceToUnlink)

Unlink a single 1:n or m:n object.

Parameters:

source - The source object with reference.

cds - The CollectionDescriptor of the relation.

referenceToUnlink - The referenced object to link.

link

public void link(Object source,
                 CollectionDescriptor cds,
                 List referencesToLink)

Link a bunch of 1:n or m:n objects.

Parameters:

source - The source object with reference.

cds - The CollectionDescriptor of the relation.

referencesToLink - List of referenced objects to link.

link

public void link(Object source,
                 CollectionDescriptor cds,
                 Object referenceToLink)

Link a single 1:n or m:n object.

Parameters:

source - The source object with the declared reference.

cds - The CollectionDescriptor of the relation declared in source object.

referenceToLink - The referenced object to link.

getCollectionIterator

public static Iterator getCollectionIterator(Object collectionOrArray)

Returns an Iterator instance for Collection, object Array or ManageableCollection instances.

Parameters:

collectionOrArray - a none null object of type Collection, Array or ManageableCollection.

Returns:

Iterator able to handle given collection object

getCollectionArray

public static Object[] getCollectionArray(Object collectionOrArray)

Returns an object array for Collection, array or ManageableCollection instances.

Parameters:

collectionOrArray - a none null object of type Collection, Array or ManageableCollection.

Returns:

Object array able to handle given collection or array object

hasAnonymousKeyReference

public static boolean hasAnonymousKeyReference(ClassDescriptor cld,
                                               ObjectReferenceDescriptor rds)

Returns true if one or more anonymous FK fields are used.

Parameters:

cld - The ClassDescriptor of the main object.

rds - The ObjectReferenceDescriptor of the referenced object.

Returns:

true if one or more anonymous FK fields are used for specified reference.