com.sapportals.wcm.service.relation
Interface IRelationService

[contained in: com.sap.netweaver.bc.rf.service.par - bc.rf.global.service.relation_api.jar]

All Superinterfaces:

IService

public interface IRelationService

extends IService

A service to store IRelation s between two objects.
A IRelation is relationship between two IRelationOperand s, called source and target operand.
IRelation s belong to their IRelationType , which in turn defines the type of the IRelationOperandType s for the source and target.
For example: the RelationType object with name attached-to would store the relationships between documents, thus the RelationOperandTypes for source and target operands are IRelation s. A specific relationship like ' /documents/public/specification.doc is attached-to /documents/public/infos/project.doc ' is then a IRelation object.

Field Summary

static java.lang.String

NAMESPACE

Method Summary

IRelationTypeAttributes	checkRelationTypeAttributes(IRelationTypeAttributes attributes, IRelationOperandType sourceType, IRelationOperandType targetType) Get a checked set of attributes which are compatible with the given source and target operand types and can be use to created a IRelationType .
IRelationType	createRelationType(IResourceContext context, java.lang.String namespace, java.lang.String name, Descriptions descriptions, IRelationOperandType sourceType, IRelationOperandType targetType) Create a new relation type for a given namespace and name if it does not already exist.
IRelationType	createRelationType(IResourceContext context, java.lang.String namespace, java.lang.String name, Descriptions descriptions, IRelationOperandType sourceType, IRelationOperandType targetType, IRelationTypeAttributes attributes) Create a new relation type for a given namespace, name and set of attributes if it does not already exist.
IRelationType	createResourceRelationType(IResourceContext context, java.lang.String namespace, java.lang.String name, Descriptions descriptions, IRelationTypeAttributes attributes) Convenience method to create a relation type for resources as source and target.
IRelationType	createStringRelationType(IResourceContext context, java.lang.String namespace, java.lang.String name, Descriptions descriptions, IRelationTypeAttributes attributes) Convenience method to create a relation type for resources as source and strings as target.
IRelationQueryBuilder	getQueryBuilder() Get a query builder to build search query expressions and order expressions for retrieving relations.
IRelationList	getRelationList() Get an empty list for relations.
IOrderedRelationPositioningList	getRelationPositioningList() Get an empty list for reordering.
IRelationList	getRelations(IResourceContext context, IRelationOperand source, IRelationOperand target) Get all relations of any type for the given source and target.
IRelationList	getRelations(IResourceContext context, IRelationQuery query) Get the relations which match a given query expression.
IRelationList	getRelations(IResourceContext context, IRelationQuery query, IRelationQueryOrder order) Get the relations which match a given query expression, ordered by a given order expression.
IRelationList	getRelationsBySource(IResourceContext context, IRelationOperand source) Get all relations of any type for the given source.
IRelationList	getRelationsByTarget(IResourceContext context, IRelationOperand target) Get all relations of any type for the given target.
IRelationType	getRelationType(IResourceContext context, java.lang.String namespace, java.lang.String name) Get a specific relation type for a given namespace and name.
IRelationTypeAttributes	getRelationTypeAttributes(IRelationTypeHandler typeHandler, IPropertyNameList requiredProperties, boolean oneToOne, boolean ordered, boolean sourceDeleteTracking, boolean targetDeleteTracking, boolean sourceChangeTracking, boolean targetChangeTracking) Same as getRelationTypeAttributes(IRelationTypeHandler, IPropertyNameList, boolean, boolean, boolean, boolean, boolean, boolean, boolean, boolean) with sourceCopyTracking and targetCopyTracking set to false
IRelationTypeAttributes	getRelationTypeAttributes(IRelationTypeHandler typeHandler, IPropertyNameList requiredProperties, boolean oneToOne, boolean ordered, boolean sourceDeleteTracking, boolean targetDeleteTracking, boolean sourceChangeTracking, boolean targetChangeTracking, boolean sourceCopyTracking, boolean targetCopyTracking) Get a set of unchecked attributes which can be use to created a IRelationType .
IRelationTypeHandler	getRelationTypeHandler(java.lang.String id) Get a type handler for a relation type (which defines 'workarea' for a relation type, like caches and tablespaces).
IRelationTypeList	getRelationTypeList() Get an empty list for relation types.
IRelationTypeList	getRelationTypes(IResourceContext context) Get a list of all relation types which are available within the given context.
IRelationTypeList	getRelationTypes(IResourceContext context, java.lang.String namespace) Get a list of all relation types of the given namespace which are available within the given context.

Methods inherited from interface com.sapportals.wcm.service.IService

getDescription, getDescription, getID

Field Detail

NAMESPACE

public static final java.lang.String NAMESPACE

Method Detail

getQueryBuilder

public IRelationQueryBuilder getQueryBuilder()
                                      throws ResourceException

Get a query builder to build search query expressions and order expressions for retrieving relations.

Returns:

a IQueryBuilder which builds query and order expressions which can be used with the getRelations(IResourceContext, IRelationQuery) and the getRelations(IResourceContext, IRelationQuery, IRelationQueryOrder) methods.

Throws:

ResourceException - if there was an internal error while retrieving the query builder.

getRelationTypeHandler

public IRelationTypeHandler getRelationTypeHandler(java.lang.String id)
                                            throws ResourceException

Get a type handler for a relation type (which defines 'workarea' for a relation type, like caches and tablespaces).

Parameters:

id - a String with the id of the type handler to retrieve or null to get the default type handler.

Returns:

the IRelationTypeHandler for the given id, or null if no such handler exists.

Throws:

ResourceException - Exception raised in failure situation

ResourceException - if there was an internal error while retrieving the handler.

See Also:

getRelationTypeAttributes(IRelationTypeHandler, IPropertyNameList, boolean, boolean, boolean, boolean, boolean, boolean)

getRelationTypeAttributes

public IRelationTypeAttributes getRelationTypeAttributes(IRelationTypeHandler typeHandler,
                                                         IPropertyNameList requiredProperties,
                                                         boolean oneToOne,
                                                         boolean ordered,
                                                         boolean sourceDeleteTracking,
                                                         boolean targetDeleteTracking,
                                                         boolean sourceChangeTracking,
                                                         boolean targetChangeTracking)
                                                  throws InvalidArgumentException,
                                                         ResourceException

Same as getRelationTypeAttributes(IRelationTypeHandler, IPropertyNameList, boolean, boolean, boolean, boolean, boolean, boolean, boolean, boolean) with sourceCopyTracking and targetCopyTracking set to false

Parameters:

typeHandler - TBD: Description of the incoming method parameter

requiredProperties - TBD: Description of the incoming method parameter

oneToOne - TBD: Description of the incoming method parameter

ordered - TBD: Description of the incoming method parameter

sourceDeleteTracking - TBD: Description of the incoming method parameter

targetDeleteTracking - TBD: Description of the incoming method parameter

sourceChangeTracking - TBD: Description of the incoming method parameter

targetChangeTracking - TBD: Description of the incoming method parameter

Returns:

relationTypeAttributes

Throws:

InvalidArgumentException - Exception raised in failure situation

ResourceException - Exception raised in failure situation

getRelationTypeAttributes

public IRelationTypeAttributes getRelationTypeAttributes(IRelationTypeHandler typeHandler,
                                                         IPropertyNameList requiredProperties,
                                                         boolean oneToOne,
                                                         boolean ordered,
                                                         boolean sourceDeleteTracking,
                                                         boolean targetDeleteTracking,
                                                         boolean sourceChangeTracking,
                                                         boolean targetChangeTracking,
                                                         boolean sourceCopyTracking,
                                                         boolean targetCopyTracking)
                                                  throws InvalidArgumentException,
                                                         ResourceException

Get a set of unchecked attributes which can be use to created a IRelationType .
These attributes may not be compatible with the specific IRelationOperandType s of a IRelationType , see checkRelationTypeAttributes(IRelationTypeAttributes, IRelationOperandType, IRelationOperandType).

Parameters:

typeHandler - a IRelationTypeHandler which defines the workarea for this relation type (see getRelationTypeHandler(String))

requiredProperties - a IPropertyNameList with the names of the required properties.

oneToOne - a boolean true if only one relation per source operand id is allowed (1:1 relations).

ordered - a boolean true if the relations have an intrinsic order per type and source operand. Note that it doesn't make much sense together with the oneToOne flag!

sourceDeleteTracking - a boolean true if relations should be deleted when their source operand is deleted.

targetDeleteTracking - a boolean true if relations should be deleted when their target operand is deleted.

sourceChangeTracking - a boolean true if the relations source operand should be changed when the object it references is moved.

targetChangeTracking - a boolean true if the relations target operand should be changed when the object it references is moved.

sourceCopyTracking - a boolean true if the another relation should be created between source-copy and target, when an exisiting relations source is copied.

targetCopyTracking - TBD: Description of the incoming method parameter

Returns:

the unchecked IRelationTypeAttributes for the given parameters.

Throws:

InvalidArgumentException - Exception raised in failure situation

ResourceException - Exception raised in failure situation

InvalidArgumentException - if the given typeHandler is not usable with this service.

ResourceException - if there was an internal error getting the relation type attributes.

See Also:

createRelationType(IResourceContext, String, String, Descriptions, IRelationOperandType, IRelationOperandType, IRelationTypeAttributes)

checkRelationTypeAttributes

public IRelationTypeAttributes checkRelationTypeAttributes(IRelationTypeAttributes attributes,
                                                           IRelationOperandType sourceType,
                                                           IRelationOperandType targetType)
                                                    throws InvalidArgumentException,
                                                           ResourceException

Get a checked set of attributes which are compatible with the given source and target operand types and can be use to created a IRelationType .
Features that are not supported are set to false, e.g. if the given sourceDeleteTracking -parameter is true , but the specified sourceType does not support delete tracking, this method will reset the sourceDeleteTracking -parameter to false in the attributes it returns.

Parameters:

attributes - the IRelationTypeAttributes to check against the given operand types.

sourceType - the IRelationOperandType of the source operands.

targetType - the IRelationOperandType of the target operands.

Returns:

the checked IRelationTypeAttributes .

Throws:

InvalidArgumentException - if the given source- or targetType is null , or if the given attribute's typeHandler is not usable with this service.

ResourceException - if there was an internal error checking the relation type attributes.

See Also:

createRelationType(IResourceContext, String, String, Descriptions, IRelationOperandType, IRelationOperandType, IRelationTypeAttributes)

createResourceRelationType

public IRelationType createResourceRelationType(IResourceContext context,
                                                java.lang.String namespace,
                                                java.lang.String name,
                                                Descriptions descriptions,
                                                IRelationTypeAttributes attributes)
                                         throws NameAlreadyExistsException,
                                                InvalidArgumentException,
                                                AccessDeniedException,
                                                ResourceException

Convenience method to create a relation type for resources as source and target.
Attributes are checked within this method, the rest is like with createRelationType(IResourceContext, String, String, Descriptions, IRelationOperandType, IRelationOperandType, IRelationTypeAttributes) with both IRelationOperandType s set to ResourceOperandType .

Parameters:

context - the IResourceContext to use for creating the relation type.

namespace - a String with the namespace of the relation type.

name - a String with the name of the relation type.

descriptions - the set of Descriptions for this relation type. if null , a default description is build from namespace and name.

attributes - a set of IRelationTypeAttributes to be used for this relation type, may be unchecked. if null , the default attributes are used.

Returns:

a IRelationType with the given parameters, for resource-type sources and resource-type targets.

Throws:

NameAlreadyExistsException - if the given namespace and name are already assigned to a relation type.

InvalidArgumentException - if the given namespace or name are not valid (exceed the maximum length of 255 chars when encoded) or the given context is null .

AccessDeniedException - if the relation type could not be created within the given context.

ResourceException - if there was an internal error creating the relation type.

createStringRelationType

public IRelationType createStringRelationType(IResourceContext context,
                                              java.lang.String namespace,
                                              java.lang.String name,
                                              Descriptions descriptions,
                                              IRelationTypeAttributes attributes)
                                       throws NameAlreadyExistsException,
                                              InvalidArgumentException,
                                              AccessDeniedException,
                                              ResourceException

Convenience method to create a relation type for resources as source and strings as target.
Attributes are checked within this method, the rest is like with createRelationType(IResourceContext, String, String, Descriptions, IRelationOperandType, IRelationOperandType, IRelationTypeAttributes) with sourceType set to ResourceOperandType and targetType set to StringOperandType .

Parameters:

context - the IResourceContext to use for creating the relation type.

namespace - a String with the namespace of the relation type.

name - a String with the name of the relation type.

descriptions - the set of Descriptions for this relation type. if null , a default description is build from namespace and name.

attributes - a set of IRelationTypeAttributes to be used for this relation type, may be unchecked. if null , the default attributes are used.

Returns:

a IRelationType with the given parameters, for resource-type sources and string-type targets.

Throws:

NameAlreadyExistsException - if the given namespace and name are already assigned to a relation type.

InvalidArgumentException - if the given namespace or name are not valid (exceed the maximum length of 255 chars when encoded) or the given context is null .

AccessDeniedException - if the relation type could not be created within the given context.

ResourceException - if there was an internal error creating the relation type.

createRelationType

public IRelationType createRelationType(IResourceContext context,
                                        java.lang.String namespace,
                                        java.lang.String name,
                                        Descriptions descriptions,
                                        IRelationOperandType sourceType,
                                        IRelationOperandType targetType)
                                 throws NameAlreadyExistsException,
                                        InvalidArgumentException,
                                        AccessDeniedException,
                                        ResourceException

Create a new relation type for a given namespace and name if it does not already exist. Same as createRelationType(IResourceContext, String, String, Descriptions, IRelationOperandType, IRelationOperandType, IRelationTypeAttributes) with attributes set to null .

Parameters:

context - the IResourceContext to use for creating the relation type.

namespace - a String with the namespace of the relation type.

name - a String with the name of the relation type.

descriptions - the set of Descriptions for this relation type. if null , a default description is build from namespace and name.

sourceType - the IRelationOperandType for the source operands, e.g. ResourceOperand

targetType - the IRelationOperandType for the target operands, e.g. StringOperand

Returns:

a IRelationType for the given namespace and name.

Throws:

NameAlreadyExistsException - Exception raised in failure situation

InvalidArgumentException - Exception raised in failure situation

AccessDeniedException - Exception raised in failure situation

ResourceException - Exception raised in failure situation

InvalidArgumentException - if the given namespace or name are not valid (exceed the maximum length of 255 chars when encoded) or the given context is null .

AccessDeniedException - if the relation type could not be created within the given context.

ResourceException - if there was an internal error creating the relation type.

createRelationType

public IRelationType createRelationType(IResourceContext context,
                                        java.lang.String namespace,
                                        java.lang.String name,
                                        Descriptions descriptions,
                                        IRelationOperandType sourceType,
                                        IRelationOperandType targetType,
                                        IRelationTypeAttributes attributes)
                                 throws NameAlreadyExistsException,
                                        InvalidArgumentException,
                                        AccessDeniedException,
                                        ResourceException

Create a new relation type for a given namespace, name and set of attributes if it does not already exist.

Parameters:

context - the IResourceContext to use for creating the relation type.

namespace - a String with the namespace of the relation type, e.g. http://sap.com/xmlns/cm/service/relations .

name - a String with the name of the relation type, e.g. attached-to .

descriptions - the set of Descriptions for this relation type in several languages. if null , a default description is build from namespace and name).

sourceType - the IRelationOperandType for the source operands.

targetType - the IRelationOperandType for the target operands.

attributes - TBD: Description of the incoming method parameter

Returns:

a IRelationType with the relation type for the given namespace and name.

Throws:

NameAlreadyExistsException - if the given namespace and name are already assigned to a relation type.

InvalidArgumentException - if the given namespace or name are not valid (exceed the maximum length of 255 chars when encoded) or the given context is null .

AccessDeniedException - if the relation type could not be created within the given context.

ResourceException - if there was an internal error creating the relation type.

getRelationTypeList

public IRelationTypeList getRelationTypeList()
                                      throws ResourceException

Get an empty list for relation types.

Returns:

an empty IRelationTypeList .

Throws:

ResourceException - if there was an internal error retrieving the list.

getRelationTypes

public IRelationTypeList getRelationTypes(IResourceContext context)
                                   throws InvalidArgumentException,
                                          ResourceException

Get a list of all relation types which are available within the given context.

Parameters:

context - the IResourceContext to use for retrieving the relation types.

Returns:

a IRelationTypeList with the list of relation types.

Throws:

InvalidArgumentException - if the given context is null .

ResourceException - if there was an internal error retrieving the relations.

getRelationTypes

public IRelationTypeList getRelationTypes(IResourceContext context,
                                          java.lang.String namespace)
                                   throws InvalidArgumentException,
                                          ResourceException

Get a list of all relation types of the given namespace which are available within the given context.

Parameters:

context - the IResourceContext to use for retrieving the relation types.

namespace - a String with the namespace of the relation types to search for.

Returns:

a IRelationTypeList with the list of relation types.

Throws:

InvalidArgumentException - Exception raised in failure situation

ResourceException - Exception raised in failure situation

InvalidArgumentException - if the given namespace is not valid (exceed the maximum length of 255 chars when encoded) or the given context is null .

ResourceException - if there was an internal error in the relation manager.

getRelationType

public IRelationType getRelationType(IResourceContext context,
                                     java.lang.String namespace,
                                     java.lang.String name)
                              throws InvalidArgumentException,
                                     AccessDeniedException,
                                     ResourceException

Get a specific relation type for a given namespace and name.

Parameters:

context - the IResourceContext to use for retrieving the relation type.

namespace - a String with the namespace of the relation type to look for.

name - a String with the name of the relation type to look for.

Returns:

a IRelationType with the relation type for the given namespace and name, or null if no such relation type exists.

Throws:

InvalidArgumentException - if the given namespace or name are not valid (exceed the maximum length of 255 chars when encoded) or if the given context is null .

AccessDeniedException - if the relation type could not be accessed within the given context.

ResourceException - if there was an internal error in the relation manager.

getRelationList

public IRelationList getRelationList()
                              throws ResourceException

Get an empty list for relations.

Returns:

an empty IRelationList .

Throws:

ResourceException - if there was an internal error retrieving the list.

getRelations

public IRelationList getRelations(IResourceContext context,
                                  IRelationQuery query)
                           throws InvalidArgumentException,
                                  RelationQueryException,
                                  ResourceException

Get the relations which match a given query expression.
The query expression can be build using the IRelationQueryBuilder returned from getQueryBuilder().

Parameters:

context - the IResourceContext to use for retrieving the relations.

query - the IRelationQuery the searched relations must match. if null , all relations will be returned.

Returns:

a IRelationList with all the relations that match the given query. the list might be empty if no matching relations are found. the list might become very large, if the query is not properly specified.

Throws:

InvalidArgumentException - if the given query is not understood or the given context is null .

RelationQueryException - if the relation query was not understood.

ResourceException - if there was an internal error executing the query or retrieving the relations.

getRelations

public IRelationList getRelations(IResourceContext context,
                                  IRelationQuery query,
                                  IRelationQueryOrder order)
                           throws InvalidArgumentException,
                                  AccessDeniedException,
                                  RelationQueryException,
                                  ResourceException

Get the relations which match a given query expression, ordered by a given order expression.
Not yet supported!
The query and the order expressions can be build using the IRelationQueryBuilder returned from getQueryBuilder().

Parameters:

context - the IResourceContext to use for retrieving the relations.

query - the IRelationQuery the searched relations must match. if null , all relations will be returned.

order - the IRelationQueryOrder the searched relation list will be sorted with. if null , the list is not ordered (same as getRelations(IResourceContext, IRelationQuery )

Returns:

a IRelationList with all the relations that match the given query. the list might be empty if no matching relations are found. the list might become very large, if the query is not properly specified.

Throws:

AccessDeniedException - Exception raised in failure situation

InvalidArgumentException - if the given query is not understood or the given context is null .

RelationQueryException - if the relation query was not understood.

ResourceException - if there was an internal error executing the query or retrieving the relations.

getRelationsBySource

public IRelationList getRelationsBySource(IResourceContext context,
                                          IRelationOperand source)
                                   throws InvalidArgumentException,
                                          ResourceException

Get all relations of any type for the given source.

Parameters:

context - the IResourceContext to use for retrieving the relations.

source - the IRelationOperand which belongs to the searched relations as source operand.

Returns:

a IRelationList with all the relations for the given source operand. the list might be empty if no matching relations are found.

Throws:

InvalidArgumentException - if the given source operand is null .

ResourceException - if there was an internal error while retrieving the relations.

getRelationsByTarget

public IRelationList getRelationsByTarget(IResourceContext context,
                                          IRelationOperand target)
                                   throws InvalidArgumentException,
                                          ResourceException

Get all relations of any type for the given target.

Parameters:

context - the IResourceContext to use for retrieving the relations.

target - the IRelationOperand which belongs to the searched relations as target operand.

Returns:

a IRelationList with all the relations for the given target operand. the list might be empty if no matching relations are found.

Throws:

InvalidArgumentException - if the given target operand is null .

ResourceException - if there was an internal error while retrieving the relations.

getRelations

public IRelationList getRelations(IResourceContext context,
                                  IRelationOperand source,
                                  IRelationOperand target)
                           throws InvalidArgumentException,
                                  ResourceException

Get all relations of any type for the given source and target.

Parameters:

context - the IResourceContext to use for retrieving the relations.

source - the IRelationOperand which belongs to the searched relations as source operand.

target - the IRelationOperand which belongs to the searched relations as target operand.

Returns:

a IRelationList with all the relations for the given source and target operand. the list might be empty if no matching relations are found.

Throws:

InvalidArgumentException - if the given source or target operand is null .

ResourceException - if there was an internal error while retrieving the relations.

getRelationPositioningList

public IOrderedRelationPositioningList getRelationPositioningList()
                                                           throws ResourceException

Get an empty list for reordering.
Not yet supported!

Returns:

a IOrderedRelationPositioningList .

Throws:

ResourceException - if the list could not be created.