com.sap.tc.col.client.generic.api
Interface IAspect

public interface IAspect

realizes an interface of an Aspect.

Data of a ServiceModule is accessible at runtime in form of various Aspects. Each Aspect contains a list of AspectRows, which all have the same structure. Besides the access methods to AspectRows, it has additional methods to create Actionss and ValueSets and to navigate to related Aspects.

Changes on Aspects (insert, update, delete) are locally buffered and managed, until a sendChanges() method is called. Then these changes are sent in one step to service queue. An example could look like:

  ...
  IAspectRow newRow = aspect.createAspectRow();
  newRow.setAttributeValue("NAME", "XXXX");  
  ....
  IAspectRow existingRow = aspect.getAspectRow(0); 
  existingRow.setAttributeValue("PRICE", "1.25");
  ....
  // now save all changes
  aspect.sendChanges();
  ...
 

There are three ways to get an IAspect:

• create and execute an IQuery and navigate from the result to the wished aspect
• create a new, empty aspect with IServiceModule.createAspect(String)
• create a new aspect with IServiceModule#getAspect(String, KeyList), where the returned Aspect is the result of a select call for all Keys of the input KeyList

In the second and third case the Aspect is root object of a cache, where the cache contains all Aspects, which were reached with navigation from this root object.

An Aspect implements the List interface, but some of the optional methods of List throw an UnsupportedOperationException, to avoid unnecessary and error producing functionality, f.i. it is not allowed to add an AspectRow other than with the method createAspectRow.

Method Summary

IAction	createAction(java.lang.String actionName) creates an Action for the given action name.
IAspectRow	createAspectRow() creates an empty AspectRow locally and adds it to the AspectRow list.
IAspectRow	createAspectRow(IKey parentKey) creates an empty AspectRow locally and adds it to the AspectRow list.
IAspectRow	createRelatedAspectRow(IKey key) Deprecated. use createAspectRow(IKey parentKey) instead
IValueSet	createValueSet(java.lang.String fieldName) creates an ValueSet for the attribute with given field name.
IAspect	getAspect(java.lang.String aspectName) Returns the sibling Aspect with given name for all keys from this Aspect instance.
IAspect	getAspect(java.lang.String aspectName, LockStrategy lockStrategy) Returns the sibling Aspect with given name for all keys from this Aspect instance.
IAspectRow	getAspectRow(IKey key) returns the AspectRow of this Aspect with given key, if there is one or null if no one exists.
IAspectRow	getAspectRow(IKey key, LockStrategy lockStrategy) returns the AspectRow of this Aspect with given key, if there is one or null if no one exists.
IAspectRow	getAspectRow(int row) returns the AspectRow with given row index or an ArrayIndexOutOfBoundsException, if row is no valid index.
IAspectRow	getAspectRow(int row, LockStrategy lockStrategy) returns the AspectRow with given row index or an ArrayIndexOutOfBoundsException, if row is no valid index.
IAspectDescriptor	getDescriptor() Returns the meta data of this Aspect.
IAspect	getKeyAspect() Returns the KeyAspect for all keys of this Aspect instance.
IKeyList	getKeyList() Returns the KeyList of this Aspect
IMessageList	getMessages() Returns the list of messages attached to this Aspect.
IAspect	getRelatedAspect(java.lang.String relationName) Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.
IAspect	getRelatedAspect(java.lang.String relationName, LockStrategy lockStrategy) Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.
IAspect	getRelatedAspect(java.lang.String relationName, LockStrategy lockStrategy, SortingCriteria sorting) Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.
IAspect	getRelatedAspect(java.lang.String relationName, java.lang.String targetAspectName) navigates to the Aspect with given targetAspectName according to the relation with given relation name and the given targetAspectName.
IAspect	getRelatedAspect(java.lang.String relationName, java.lang.String targetAspectName, LockStrategy lockStrategy) navigates to the Aspect with given targetAspectName according to the relation with given relation name and the given targetAspectName.
IServiceModule	getServiceModule() Returns the ServiceModule this Aspect belongs to.
void	invalidate() invalidates this Aspect and the corresponding sub tree of the cache starting with this Aspect.
boolean	isValid() Returns true if this Aspect is valid, otherwise false.
void	promoteLock() Promote all SHARED_PROMOTABLE locks to EXCLUSIVE locks.
void	refresh() requests the refresh of the cache or a sub tree of the cache starting from this Aspect.
boolean	removeAspectRow(IAspectRow aspectRow) removes an AspectRow from the AspectRow list locally.
boolean	removeAspectRow(IAspectRow aspectRow, LockStrategy lockStrategy) removes an AspectRow from the AspectRow list locally.
void	sendChanges() Sends all pending changes of this Aspect to service layer.
void	setInvalidationHint(java.lang.String actionName, int affects) sets invalidation hint for this Aspect and the Action with given actionName.
void	unlock() Release any lock previously acquired for rows of this aspect.

Method Detail

getAspectRow

public IAspectRow getAspectRow(IKey key)

returns the AspectRow of this Aspect with given key, if there is one or null if no one exists.

Parameters:

key - the Key of the AspectRow to be returned.

Returns:

IAspectRow the found AspectRow or null, if not exists.

getAspectRow

public IAspectRow getAspectRow(IKey key,
                               LockStrategy lockStrategy)

returns the AspectRow of this Aspect with given key, if there is one or null if no one exists.

if lockStrategy other than

null

is set, the AspectRow is locked according to the given lockStrategy and then refreshed. A backend rounddrip is therefore necessary.

Parameters:

key - the Key of the AspectRow

lockStrategy - strategy how the target AspectRow should be locked, possible strategies are defined in ILockStrategy

Returns:

IAspectRow the found AspectRow or null, if not exists.

getAspectRow

public IAspectRow getAspectRow(int row)

returns the AspectRow with given row index or an ArrayIndexOutOfBoundsException, if row is no valid index.

Parameters:

row - the index of the AspectRow to return

Returns:

IAspectRow the found AspectRow or ArrayIndexOutOfBoundsException if not exists

Throws:

ArrayIndexOutOfBoundsException -

getAspectRow

public IAspectRow getAspectRow(int row,
                               LockStrategy lockStrategy)

returns the AspectRow with given row index or an ArrayIndexOutOfBoundsException, if row is no valid index.

if lockStrategy other than

null

is set, the AspectRow is locked according to the given lockStrategy and refreshed. A backend rounddrip is therefore necessary.

Parameters:

row - the index of the AspectRow to return

lockStrategy - strategy how the target AspectRow should be locked, possible strategies are defined in ILockStrategy

Returns:

IAspectRow the found AspectRow.

Throws:

ArrayIndexOutOfBoundsException - AspectRow with given index doesn't exist.

createAspectRow

public IAspectRow createAspectRow()

creates an empty AspectRow locally and adds it to the AspectRow list.

Cause no key for the row is given, an empty key (local key) is created. Additionally if

IAspectDescriptor.getAttributeInsertRelationRequired() == true

, the method tries to find the parent key of the predefined (by meta data) relation to this Aspect, and if the Key is found the method works like createAspectRow(IKey) Additionally the local insert of this AspectRow is registered and will be sent to backend, when method sendChanges() is called.

Example:

   IAspectRow myRow = aspect.createAspectRow();
   myRow.setAttributeValue("NAME1", "BLABLA");
   ..
   aspect.sendChanges();
   ..
 

Returns:

IAspectRow the new created AspectRow

createAspectRow

public IAspectRow createAspectRow(IKey parentKey)

creates an empty AspectRow locally and adds it to the AspectRow list.

Cause no key for the new AspectRow is given, an empty key (local key) is created.

Additionally a predefined (by meta data ) relation from AspectRow with given Key (parentKey) is created, too, when insert is done in backend.

If the meta data are not set correctly means:

IAspectDescriptor.getAttributeInsertRelationRequired() == false

the method throws an IllegalArgumentException.

If parentKey parameter is null the method tries to find the parents Key in the creation path of this Aspect. If this parentKey can't be found an IllegalArgumentException is thrown, too. Additionally the local insert of this AspectRow is registered and will be sent to backend, when method sendChanges() is called.

Example:

   IAspectRow myRow = aspect.createAspectRow();
   myRow.setAttributeValue("NAME1", "BLABLA");
   ..
   aspect.sendChanges();
   ..
 

Parameters:

parentKey - the key of the parent AspectRow of the relation, where the new AspectRow should be created.

Returns:

IAspectRow the new created AspectRow

createRelatedAspectRow

public IAspectRow createRelatedAspectRow(IKey key)

Deprecated. use

createAspectRow(IKey parentKey)

instead

creates an empty AspectRow locally and adds it to the AspectRow list. Additionally a predefined (by meta data ) relation from AspectRow with given Key is created, too, when insert is done in backend.

Cause no key for the row is given, an empty key (local key) is created. Additionally the local insert of this AspectRow is registered together with the additional relation information and will be sent to backend, when method sendChanges() is called.

Example:

   IAspectRow myRow = aspect.createRelatedAspectRow(keyOrder );
   myRow.setAttributeValue("ITEM_ID", "40");
   ..
   aspect.sendChanges();
   ..
 

the method throws an UnsupportedOperationException, if this Aspect doesn't support this kind of insert. This information is provided by the meta data of the Aspect.

Parameters:

key - the Key of the source AspectRow of the relation.

Returns:

IAspectRow the new created AspectRow

removeAspectRow

public boolean removeAspectRow(IAspectRow aspectRow)

removes an AspectRow from the AspectRow list locally. Additionally the local delete is registered and is sent to backend, when method sendChanges() is called.

Example:

   aspect.removeAspectRow( myRow );
   ..
   aspect.sendChanges();
   ..
 

Parameters:

aspectRow - the row to be deleted

Returns:

boolean returns true if the operation was successful, otherwise false

removeAspectRow

public boolean removeAspectRow(IAspectRow aspectRow,
                               LockStrategy lockStrategy)

removes an AspectRow from the AspectRow list locally. Additionally the local delete is registered and is sent to backend, when method sendChanges() is called.

if lockStrategy other than

null

is set, the corresponding lock is promoted to backend before the AspectRow is deleted.

Parameters:

aspectRow - the AspectRow to be deleted

lockStrategy - strategy how the target AspectRow should be locked, possible strategies are defined in ILockStrategy

Returns:

boolean returns true if the operation was successful, otherwise false

createAction

public IAction createAction(java.lang.String actionName)

creates an Action for the given action name. if actionName is no supported Action, an IllegalArgumentException is thrown

Parameters:

actionName - the name of the Action

Returns:

IAction the created Action

Throws:

java.lang.IllegalArgumentException - actionName is no supported Action

createValueSet

public IValueSet createValueSet(java.lang.String fieldName)

creates an ValueSet for the attribute with given field name. if no ValueSet exists for this fieldName, an IllegalArgumentException is thrown

Parameters:

fieldName - the name of the field, for which the ValueSet should be created

Returns:

IValueSet the created ValueSet interface

Throws:

java.lang.IllegalArgumentException - no ValueSet is available for fieldName.

getRelatedAspect

public IAspect getRelatedAspect(java.lang.String relationName)

Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.

If this method has been called earlier and if no refresh or invalidation occured in the meantime, then a cached instance of this Aspect will be returned.

The relationName has to be the name of a relation, starting from this Aspect or its Key Aspect, otherwise an IllegalArgumentException is thrown.

Parameters:

relationName - the name of the relation to follow

Returns:

IAspect the target Aspect of the relation

Throws:

java.lang.IllegalArgumentException - relationName is no valid Relation for this Aspect or its Key

getRelatedAspect

public IAspect getRelatedAspect(java.lang.String relationName,
                                LockStrategy lockStrategy)

Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.

If this method has been called earlier and if no invalidation occured in the meantime, then a cached instance of this Aspect will be returned.

The relationName has to be the name of a relation, starting from this Aspect or its Key Aspect, otherwise an IllegalArgumentException is thrown.

if lockStrategy other than

null

is set, locking is only possible, if target Aspect is in state CLEAN (target Aspect is buffered ) or HOLLOW ( not yet read ). Otherwise it throws an IllegalStateException. The lock (Shared, SP or Exclusive) resulting from lock strategy is promoted to backend and the Aspect is read or refreshed with this lock.

Cause locking is also possible on AspectRow level, the method checks the consistency of the AspectRows lock states and strategies and if there are inconsistencies found, an IllegalStateException is thrown.

Parameters:

relationName - the name of the relation

lockStrategy - strategy how the target AspectRows should be locked, possible strategies are defined in ILockStrategy

Returns:

IAspect the target Aspect of the relation

Throws:

java.lang.IllegalArgumentException - relationName is no valid Relation for this Aspect or its Key

IllegalStateException - Aspect has no valid state for locking or lock state of the different AspectRows is inconsistent.

getRelatedAspect

public IAspect getRelatedAspect(java.lang.String relationName,
                                LockStrategy lockStrategy,
                                SortingCriteria sorting)

Navigates to the target Aspect according to the relation with given relation name, where relation may be a relation for this Aspect or its Key.

If this method has been called earlier and if no invalidation occured in the meantime, then a cached instance of this Aspect will be returned.

The relationName has to be the name of a relation, starting from this Aspect or its Key Aspect, otherwise an IllegalArgumentException is thrown.

if lockStrategy other than

null

is set, locking is only possible, if target Aspect is in state CLEAN (target Aspect is buffered ) or HOLLOW ( not yet read ). Otherwise it throws an IllegalStateException. The lock (Shared, SP or Exclusive) resulting from lock strategy is promoted to backend and the Aspect is read or refreshed with this lock.

Cause locking is also possible on AspectRow level, the method checks the consistency of the AspectRows lock states and strategies and if there are inconsistencies found, an IllegalStateException is thrown. if sorting criteria are set, the target Aspect is sorted (in backend) according to these sorting criteria, but this is only valid, if the target is not taken from cache. In particular this means, that the sorting parameter only effects the target Aspect, when the relation is done the first time.

Parameters:

relationName - the name of the relation

lockStrategy - strategy how the target AspectRows should be locked, possible strategies are defined in ILockStrategy

sorting - the sorting criteria for the target Aspect

Returns:

IAspect the target Aspect of the relation

Throws:

java.lang.IllegalArgumentException - relationName is no valid Relation for this Aspect or its Key

IllegalStateException - Aspect has no valid state for locking or lock state of the different AspectRows is inconsistent.

getRelatedAspect

public IAspect getRelatedAspect(java.lang.String relationName,
                                java.lang.String targetAspectName)

navigates to the Aspect with given targetAspectName according to the relation with given relation name and the given targetAspectName.

The relationName has to be the name of a relation, starting from this Aspect or its Key Aspect, otherwise an IllegalArgumentException is thrown.

The targetAspect given in method call, may not be the targetAspect of the relation, but could be a sibling Aspect of this target. Sibling means, that it has the same Key and a 1:1 association.

The method is a convenience method, which replaces the following calls

   IAspect targetOfRelation = aspect.getRelatedAspect(relationName):
   IAspect targetAspect = targetOfRelation.getAspect(targetAspectName);
 

Parameters:

relationName - the name of the relation

targetAspectName - the name of the targetAspect to navigate to

Returns:

IAspect the target Aspect of the relation

Throws:

IllegalArgumentException - is thrown, if relationName is no valid Relation for this Aspect or its Key.

getRelatedAspect

public IAspect getRelatedAspect(java.lang.String relationName,
                                java.lang.String targetAspectName,
                                LockStrategy lockStrategy)

navigates to the Aspect with given targetAspectName according to the relation with given relation name and the given targetAspectName.

The relationName has to be the name of a relation, starting from this Aspect or its Key Aspect, otherwise an IllegalArgumentException is thrown.

The targetAspect given in method call, may not be the targetAspect of the relation, but could be a sibling Aspect of this target. Sibling means, that it has the same Key and a 1:1 association.

The method is a convenience method, which replaces the following calls

   IAspect targetOfRelation = aspect.getRelatedAspect(relationName):
   IAspect targetAspect = targetOfRelation.getAspect(targetAspectName);
 

if lockStrategy other than

null

is set, locking is only possible, if target Aspect is in state CLEAN (target Aspect is buffered ) or HOLLOW ( not yet read ). Otherwise it throws an IllegalStateException. The lock (Shared, SP or Exclusive) resulting from lock strategy is promoted to backend and the Aspect is read or refreshed with this lock.

Cause locking is also possible on AspectRow level, the method checks the consistency of the AspectRows lock states and strategies and if there are inconsistencies found, an IllegalStateException is thrown.

Parameters:

relationName - the name of the relation

targetAspectName - the name of the targetAspect to navigate to

lockStrategy - strategy how the target AspectRows should be locked, possible strategies are defined in ILockStrategy

Returns:

IAspect the target Aspect of the relation

Throws:

java.lang.IllegalArgumentException - relationName is no valid Relation for this Aspect or its Key

IllegalStateException - Aspect has no valid state for locking or lock state of the different AspectRows is inconsistent.

getAspect

public IAspect getAspect(java.lang.String aspectName)

Returns the sibling Aspect with given name for all keys from this Aspect instance.

If this method has been called earlier and if no invalidation occured in the meantime, then a cached instance of this Aspect will be returned.

Parameters:

aspectName - the name of the sibling Aspect

Returns:

IAspect an Aspect with given name for all keys from this Keys instance.

getAspect

public IAspect getAspect(java.lang.String aspectName,
                         LockStrategy lockStrategy)

Returns the sibling Aspect with given name for all keys from this Aspect instance.

if lockStrategy other than

null

is set, locking is only possible, if target Aspect is in state CLEAN (target Aspect is buffered ) or HOLLOW ( not yet read ). Otherwise it throws an IllegalStateException. The lock (Shared, SP or Exclusive) resulting from lock strategy is promoted to backend and the Aspect is read or refreshed with this lock.

Cause locking is also possible on AspectRow level, the method checks the consistency of the AspectRows lock states and strategies and if there are inconsistencies found, an IllegalStateException is thrown.

Parameters:

aspectName - the name of the sibling Aspect

lockStrategy - strategy how the target AspectRows should be locked, possible strategies are defined in ILockStrategy

Returns:

IAspect an Aspect with given name for all keys from this Keys instance.

Throws:

IllegalStateException - Aspect has no valid state for locking or lock state of the different AspectRows is inconsistent.

getKeyAspect

public IAspect getKeyAspect()

Returns the KeyAspect for all keys of this Aspect instance.

If the KeyAspect has been called earlier and if no invalidation occured in the meantime, then a cached instance of the KeyAspect will be returned. In that case, the KeyList of the returned reflects the KeyList of this aspect at the time the method was called for the first time.

This is only a convenience shortcut for

   this.getAspect(this.getDescriptor().getKeyDescriptor().getName());
 

Returns:

IAspect a KeyAspect for this aspect.

getKeyList

public IKeyList getKeyList()

Returns the KeyList of this Aspect

Returns:

IKeyList the KeyList of this Aspect

getDescriptor

public IAspectDescriptor getDescriptor()

Returns the meta data of this Aspect.

Typically meta data are name, supported relations, supported Actions, meta data of Key and meta data of AspectRow.

Returns:

AspectDescriptor the meta data of this Aspect

getServiceModule

public IServiceModule getServiceModule()

Returns the ServiceModule this Aspect belongs to.

Returns:

IServiceModule the ServiceModule this Aspect belongs to

sendChanges

public void sendChanges()

Sends all pending changes of this Aspect to service layer.

There are no special services for insert, update, delete, cause of performance reasons, we bundle and manage all local changes until this method is called. Then all changes are sent to service layer in one step. Example:

   aspect.removeAspectRow( myRow );
   myUpdatedRow = aspect.getAspectRow( myKey );
   myUpdatedRow.setAttributeValue("NAME1", "BLABLA");
   ...
   aspect.sendChanges();
   ..
 

invalidate

public void invalidate()

invalidates this Aspect and the corresponding sub tree of the cache starting with this Aspect.

After invalidation this Aspect and all Aspects in the cache are no more accessible, the references are released.

refresh

public void refresh()

requests the refresh of the cache or a sub tree of the cache starting from this Aspect.

the method itself only changes the state of this Aspect to "REFRESH_NEEDED" together with the complete sub tree of this Aspect. The refresh itself is done later on lazy, if an Aspect or AspectRow in state "REFRESH_NEEDED" is accessed.

setInvalidationHint

public void setInvalidationHint(java.lang.String actionName,
                                int affects)

sets invalidation hint for this Aspect and the Action with given actionName.

. * Since invalidating the cache on every change - however trivial it may be - would lead to bad performance. So with this method the client can tell the GCP, which side effects the triggered operations on Aspect may have. If such a hint is set, GCP will overwrite the side effects settings from repository .

Possible values for the actionName parameter are:

  IAspectActionDescriptor.ACTION_INSERT
  IAspectActionDescriptor. ACTION_UPDATE_ROW
  IAspectActionDescriptor.ACTION_UPDATE_FIELD
  IAspectActionDescriptor. ACTION_DELETE 
  or the name of a special Action of this Aspect
 

Possible values for the affects parameter are:

  IAspectActionDescriptor.AFFECTS_NOTHING
  IAspectActionDescriptor.AFFECTS_OUTRECORDS 
  IAspectActionDescriptor.AFFECTS_ASPECT 
  IAspectActionDescriptor.AFFECTS_ALL  
 

Example:

  setInvalidationHint(IAspectActionDescriptor.ACTION_INSERT, IAspectActionDescriptor.AFFECTS_ASPECT) 
 

means, that an insert on this Aspect will lead to a cache refresh, where the refresh starts from this Aspect

Parameters:

actionName - the name of the Action

affects - the affects parameter for the given Action

Throws:

throws - IllegalArgumentException, if given parameter are not allowed

getMessages

public IMessageList getMessages()

Returns the list of messages attached to this Aspect. To remove these messages explicitly you can call the clear() method of IMessageList

Returns:

IMessageList the list of messages attached to this Aspect

promoteLock

public void promoteLock()

Promote all SHARED_PROMOTABLE locks to EXCLUSIVE locks.

Lock Mode Promotion is processed in the queue as well, therefore the result of the lock promotion is only available after flushing the queue.

unlock

public void unlock()

Release any lock previously acquired for rows of this aspect.

isValid

public boolean isValid()

Returns true if this Aspect is valid, otherwise false. If this Aspect is not valid, accessing the Aspect leads to an IllegalStateException.