com.force.sdk.jpa
Class PersistenceUtils

java.lang.Object
  com.force.sdk.jpa.PersistenceUtils

public final class PersistenceUtils
extends Object

Class for general utility methods needed while persisting and retrieving objects.

Author:

Fiaz Hossain, Jill Wetzler

Field Summary

static String	JOIN_FILTER prefix for member metadata extensions on join filters.
static String	PICKLIST_VALUE_FIELD_PREFIX prefix for member metadata extensions on picklist values.

Method Summary

static String	getEntityName(org.datanucleus.metadata.AbstractClassMetaData acmd) Return the name of the entity, first checking the name attribute of the annotations and then defaulting to the entity name on the metadata object.
static String	getFieldName(org.datanucleus.metadata.AbstractMemberMetaData ammd, Map<String,String> extensions) Get the name of a field for use with JPA.
static String	getFieldNameFromJPAAnnotation(org.datanucleus.metadata.AbstractMemberMetaData ammd) Returns the name of a column as specified in a JPA annotation (can possibly be null).
static com.sforce.soap.metadata.FieldType	getFieldTypeFromForceAnnotation(Map<String,String> extensions) Utility method to get the field type from a map of extensions.
static String	getForceApiName(org.datanucleus.metadata.AbstractMemberMetaData ammd, org.datanucleus.OMFContext omf) Utility method to determine the name of a field based on the member metadata.
static Map<String,String>	getForceExtensions(org.datanucleus.metadata.MetaData md) Utility method that returns only the Force.com specific extensions for a piece of metadata (either an entity or a field).
static <T extends Annotation> T	getMemberAnnotation(Member member, Class<T> annotationClass) Returns the annotation of type T on a field or method, e.g.
static org.datanucleus.metadata.AbstractClassMetaData	getMemberElementClassMetaData(org.datanucleus.metadata.AbstractMemberMetaData ammd, org.datanucleus.ClassLoaderResolver clr, org.datanucleus.metadata.MetaDataManager mdm) Get the class metadata for a member's type.
static Object	getMemberValue(org.datanucleus.metadata.AbstractClassMetaData acmd, int position, Object entity) Retrieve the value stored at a particular position in an entity.
static Object	getMemberValue(Member member, Object entity) Retrive the value of a field on an entity via reflection.
static boolean	hasNoSchema(org.datanucleus.metadata.AbstractClassMetaData acmd) An entity does not have schema if it would not directly represent an object in Force.com, e.g.
static boolean	isMultiPicklist(org.datanucleus.metadata.AbstractMemberMetaData ammd) A check for whether a field is a multiselect picklist or a single select picklist.
static boolean	isNonPersistedColumn(org.datanucleus.metadata.AbstractMemberMetaData ammd) Check for whether a column has a Persistence Modifier that is anything other than PERSISTENT.
static boolean	isOrdinalEnum(org.datanucleus.metadata.AbstractMemberMetaData ammd) A check to see if a field has an ordinal enum type, i.e.
static boolean	isReadOnlySchema(org.datanucleus.metadata.AbstractClassMetaData acmd, boolean checkHierarchy) Performs various checks to see if the schema is read only (i.e.
static boolean	isRelationship(org.datanucleus.metadata.AbstractMemberMetaData ammd) Check for whether the field is a ManyToOne or OneToMany relationship (the only relationships currently supported).
static boolean	isVirtualSchema(org.datanucleus.metadata.AbstractClassMetaData acmd) A JPA entity is virtual schema if it is not backed by an object on Force.com (e.g.
static String	prependNamespace(String namespace, String name) Util method to prepend a namespace to a name, namespace can be null.
static void	setFieldValue(Class clazz, org.datanucleus.metadata.AbstractClassMetaData acmd, int position, Object entity, Object value) Sets the value of a field on an entity.

Methods inherited from class java.lang.Object

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

Field Detail

PICKLIST_VALUE_FIELD_PREFIX

public static final String PICKLIST_VALUE_FIELD_PREFIX

prefix for member metadata extensions on picklist values.

See Also:

Constant Field Values

JOIN_FILTER

public static final String JOIN_FILTER

prefix for member metadata extensions on join filters.

See Also:

Constant Field Values

Method Detail

getEntityName

public static String getEntityName(org.datanucleus.metadata.AbstractClassMetaData acmd)

Return the name of the entity, first checking the name attribute of the annotations and then defaulting to the entity name on the metadata object.

Parameters:

acmd - the metadata object of the JPA entity

Returns:

The name of the entity to use in JPA (entity name or JPQL queries)

hasNoSchema

public static boolean hasNoSchema(org.datanucleus.metadata.AbstractClassMetaData acmd)

An entity does not have schema if it would not directly represent an object in Force.com, e.g. if the entity is embedded or if it's a subclass of another entity

Parameters:

acmd - the metadata object of the JPA entity

Returns:

true if the entity does not have schema

isReadOnlySchema

public static boolean isReadOnlySchema(org.datanucleus.metadata.AbstractClassMetaData acmd,
                                       boolean checkHierarchy)

Performs various checks to see if the schema is read only (i.e. schema should not be created, updated, or deleted when the application starts up, regardless of whether schema creation is enabled).

Parameters:

acmd - the metadata object of the JPA entity

checkHierarchy - generally, we don't need to check the hierarchy if we're creating fields, but if we're creating tables we need to check the parent to see if the parent object is read only

Returns:

true if the schema is read only.

isVirtualSchema

public static boolean isVirtualSchema(org.datanucleus.metadata.AbstractClassMetaData acmd)

A JPA entity is virtual schema if it is not backed by an object on Force.com (e.g. Owner is not backed by an Owner object on Force.com)

Parameters:

acmd - the metadata object of the JPA entity

Returns:

true if the entity is considered virtual schema

isNonPersistedColumn

public static boolean isNonPersistedColumn(org.datanucleus.metadata.AbstractMemberMetaData ammd)

Check for whether a column has a Persistence Modifier that is anything other than PERSISTENT.

Parameters:

ammd - the metadata object representing a column or field

Returns:

true if the column is not persistent

getForceExtensions

public static Map<String,String> getForceExtensions(org.datanucleus.metadata.MetaData md)

Utility method that returns only the Force.com specific extensions for a piece of metadata (either an entity or a field).

Parameters:

md - The metadata containing extensions

Returns:

a map of the extension key and value of the extension, limited to Force.com extensions

getFieldTypeFromForceAnnotation

public static com.sforce.soap.metadata.FieldType getFieldTypeFromForceAnnotation(Map<String,String> extensions)

Utility method to get the field type from a map of extensions.

Parameters:

extensions - a Map of Force.com extensions on a metadata object

Returns:

if a type has been specified, parse to a FieldType, otherwise return null

isOrdinalEnum

public static boolean isOrdinalEnum(org.datanucleus.metadata.AbstractMemberMetaData ammd)

A check to see if a field has an ordinal enum type, i.e. it's annotated with \@Enumerated(EnumType.ORDINAL). Callers of this method should have already verified ammd to be a picklist field.

Parameters:

ammd - the metadata object of a picklist field

Returns:

true if the field is an ordinal enum

isMultiPicklist

public static boolean isMultiPicklist(org.datanucleus.metadata.AbstractMemberMetaData ammd)

A check for whether a field is a multiselect picklist or a single select picklist. Callers of this method ahould have already verified ammd to be a picklist field

Parameters:

ammd - the metadata object of a picklist field

Returns:

true if the field represents a multi select picklist, false otherwise.

isRelationship

public static boolean isRelationship(org.datanucleus.metadata.AbstractMemberMetaData ammd)

Check for whether the field is a ManyToOne or OneToMany relationship (the only relationships currently supported).

Parameters:

ammd - the metadata object for a field

Returns:

true if this field is a relationship field

getMemberValue

public static Object getMemberValue(org.datanucleus.metadata.AbstractClassMetaData acmd,
                                    int position,
                                    Object entity)
                             throws IllegalAccessException,
                                    InvocationTargetException

Retrieve the value stored at a particular position in an entity.

Parameters:

acmd - the class metadata for the entity that holds the value

position - the position of the field you want the value for

entity - the actual entity that contains the value

Returns:

the value stored in the entity at the position

Throws:

IllegalAccessException - thrown if the field cannot be accessed

InvocationTargetException - thrown if the field's get method cannot be invoked

getMemberValue

public static Object getMemberValue(Member member,
                                    Object entity)
                             throws IllegalAccessException,
                                    InvocationTargetException

Retrive the value of a field on an entity via reflection.

Parameters:

member - the Member object for a particular field on an entity

entity - the entity that contains the value

Returns:

the value stored in the entity's member object

Throws:

IllegalAccessException - thrown if the member cannot be accessed

InvocationTargetException - thrown if the member's get method cannot be invoked

getMemberAnnotation

public static <T extends Annotation> T getMemberAnnotation(Member member,
                                                           Class<T> annotationClass)

Returns the annotation of type T on a field or method, e.g. you could use this method to get the @Column or @JoinFilter annotation on a getter method for a column

Type Parameters:

T - an Annotation type

Parameters:

member - the member representing a particular field or method

annotationClass - the class of the annotation object that should be returned

Returns:

the Annotation on this field or method

setFieldValue

public static void setFieldValue(Class clazz,
                                 org.datanucleus.metadata.AbstractClassMetaData acmd,
                                 int position,
                                 Object entity,
                                 Object value)
                          throws SecurityException,
                                 NoSuchFieldException,
                                 IllegalArgumentException,
                                 IllegalAccessException

Sets the value of a field on an entity.

Parameters:

clazz - The entity class

acmd - metadata object for the entity

position - the position of the field that should be set

entity - the instance of the entity being updated

value - the value that should be set on the field

Throws:

SecurityException - thrown if the field cannot be accessed

NoSuchFieldException - thrown if the field does not exist

IllegalArgumentException - thrown if the set fails

IllegalAccessException - thrown if the set fails

getForceApiName

public static String getForceApiName(org.datanucleus.metadata.AbstractMemberMetaData ammd,
                                     org.datanucleus.OMFContext omf)

Utility method to determine the name of a field based on the member metadata. Field names can be set via JPA or Force.com annotations, and relationship fields call for special handling

Parameters:

ammd - the metadata object for the field we're retrieving a name for

omf - the Object Manager Factory context

Returns:

the name of a field/column as it would appear in the Force.com API

prependNamespace

public static String prependNamespace(String namespace,
                                      String name)

Util method to prepend a namespace to a name, namespace can be null.

Parameters:

namespace - A possibly null namespace string

name - the name of a field or object

Returns:

the name if namespace is null, otherwise the appended string

getMemberElementClassMetaData

public static org.datanucleus.metadata.AbstractClassMetaData getMemberElementClassMetaData(org.datanucleus.metadata.AbstractMemberMetaData ammd,
                                                                                           org.datanucleus.ClassLoaderResolver clr,
                                                                                           org.datanucleus.metadata.MetaDataManager mdm)

Get the class metadata for a member's type. For collections, get the metadata for the type parameter

Parameters:

ammd - The member whose class metadata you want to retrive

clr - the classloader resolver to use

mdm - the metadata manager to use

Returns:

the class metadata object for the given member

getFieldName

public static String getFieldName(org.datanucleus.metadata.AbstractMemberMetaData ammd,
                                  Map<String,String> extensions)

Get the name of a field for use with JPA. First try to get the name from the Force.com annotations, the try to get the name from standard JPA annotations, otherwise use the name of the field in Java

Parameters:

ammd - the metadata object for the field we're retrieving a name for

extensions - the Force.com extensions for this metadata (see getForceExtensions}

Returns:

the name of the field for JPQL

getFieldNameFromJPAAnnotation

public static String getFieldNameFromJPAAnnotation(org.datanucleus.metadata.AbstractMemberMetaData ammd)

Returns the name of a column as specified in a JPA annotation (can possibly be null).

Parameters:

ammd - the metadata object for the field we're retrieving a name for

Returns:

null if the field name is not defined by a JPA annotation, otherwise return the field name