Package com.im.df.api.dml

Interface DFRelationDataProvider

public interface DFRelationDataProvider

API Status: This interface is not stable. Do not use it.

Data provider for relational data. As this is still under development this class is not stable and might be changed/removed in the future.

The DataProvider represents row tuples related by a DFRelationship, in the direction described by getRelationshipDir().

The manipulation methods, addRelation(java.lang.Comparable<?>, java.util.Set<? extends java.lang.Comparable<?>>, com.im.commons.progress.DFEnvironmentRW) and removeRelation(java.lang.Comparable<?>, java.util.Set<? extends java.lang.Comparable<?>>, com.im.commons.progress.DFEnvironmentRW), are only used to connect existing rows of Entities. If you need to create data rows or delete them from the database, you have to use the DFSchemaDataProvider.

Because of different cardinalities, the add and remove methods are specified as they take a single Row ID from one side of the relation, and a collection of row IDs from the other side.

The mapping is as follows:

• MANY_TO_ONE - the destination field
• ONE_TO_MANY - the source field
• ONE_TO_ONE - the source field (reason: the relationship is directed)
• MANY_TO_MANY - the source field

This is because it is possible to clear a subset or all relations between the single "master" and its detail rows in the MANY_TO_ONE or ONE_TO_MANY case. It also allows to prune whole subsets in MANY_TO_MANY case. The ONE_TO_ONE case is just a singularity.

Author:

Svata

Method Summary

Modifier and Type	Method	Description
void	addDFRelationDataListener(DFRelationDataListener listener)
void	addRelation(java.lang.Comparable<?> idMaster, java.util.Set<? extends java.lang.Comparable<?>> idDetail, com.im.commons.progress.DFEnvironmentRW env)	Establishes or changes relations between existing entities.
com.im.commons.progress.DFLockable	getLockable()
java.util.List<? extends java.lang.Comparable<?>>	getRelatedIds(java.lang.Comparable<?> masterId, DFTermExpression filter, SortDirective sort)	Retrieves a mapping from 'masterIds' of the DFRelationship.Direction.getSrcField() to their counterparts according to the relation.
DFRelationship.Direction	getRelationshipDir()
DFSchemaDataProvider	getSchemaDataProvider()
void	removeDFRelationDataListener(DFRelationDataListener listener)
void	removeRelation(java.lang.Comparable<?> idMaster, java.util.Set<? extends java.lang.Comparable<?>> removeIDs, com.im.commons.progress.DFEnvironmentRW env)	Breaks relations between 'idMaster' row in the master entity and 'removeIDs' rows of the detail entity.

Method Detail

getLockable

com.im.commons.progress.DFLockable getLockable()

getSchemaDataProvider

DFSchemaDataProvider getSchemaDataProvider()

Returns:

The parent SchemaDataProvider

getRelationshipDir

DFRelationship.Direction getRelationshipDir()

Returns:

The relationship direction the provider operates with

getRelatedIds

java.util.List<? extends java.lang.Comparable<?>> getRelatedIds(java.lang.Comparable<?> masterId,
                                                                DFTermExpression filter,
                                                                SortDirective sort)

Retrieves a mapping from 'masterIds' of the DFRelationship.Direction.getSrcField() to their counterparts according to the relation.

The returned IDs will respect the 'sort' SortDirective applied to the results from the destination field's entity.

The method returns a Map keyed by "source" row IDs. Values are lists ordered according to the SortDirective that contain row IDs from the related entity.

Parameters:

masterId - field id from parent entity

filter - is not implemented, just use null

sort - sorting result

Returns:

The map from entity IDs to their related counterparts

addRelation

void addRelation(java.lang.Comparable<?> idMaster,
                 java.util.Set<? extends java.lang.Comparable<?>> idDetail,
                 com.im.commons.progress.DFEnvironmentRW env)
          throws DFRelationDataException

Establishes or changes relations between existing entities. Sets a relation between the 'idMaster' row and 'idDetail' rows.

Note, however, that although the method is coded as it permits to associate multiple detail entities to the master, the actual DFRelationship.Direction.getType() may restrict the operation. For *_TO_ONE relationship types, the 'idDetail' must contain exactly one item.

You may consider to use the DFRelationship provider for the 'one' side of the relationship to associate multiple items.

Throws:

DFRelationDataException

removeRelation

void removeRelation(java.lang.Comparable<?> idMaster,
                    java.util.Set<? extends java.lang.Comparable<?>> removeIDs,
                    com.im.commons.progress.DFEnvironmentRW env)
             throws DFRelationDataException

Breaks relations between 'idMaster' row in the master entity and 'removeIDs' rows of the detail entity. The meaning of 'master' changes with relationship type:

Note, however, that although the method is coded as it permits to associate multiple detail entities to the master, the actual DFRelationship.Direction.getType() may restrict the operation. For *_TO_ONE relationship types, the 'idDetail' must contain exactly one item.

You may consider to use the DFRelationship provider for the 'one' side of the relationship to break association to multiple items at once.

Note that if the field that binds the relationship in the 'detail' entity is 'required', the method will throw a DFRelationDataException, informing you which field cannot be reset.

Parameters:

idMaster - The r ow ID in the "source" entity

removeIDs - The r ow IDs in the "destination" entity

env - The DFEnvironment.

Throws:

DFRelationDataException

addDFRelationDataListener

void addDFRelationDataListener(DFRelationDataListener listener)

removeDFRelationDataListener

void removeDFRelationDataListener(DFRelationDataListener listener)