com.ibm.team.interop.common

Interface ISyncRule

All Superinterfaces:

IAuditable, IAuditableHandle, IItem, IItemHandle, IManagedItem, IManagedItemHandle, ISyncRuleHandle

public interface ISyncRule
extends ISyncRuleHandle, IAuditable

A synchronization rule defines how external object properties and Jazz item properties are transformed into each other. If an external object is being synchronized with a Jazz item (as opposed to just having some of its state replicated in the Jazz repository), the sync rule defines the association between external properties and Jazz properties, and the names of both Jazz and external "object managers" that know how to read and write the objects being synchronized.

Since:

0.5

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ENABLED_TEAM_AREAS_PROPERTY The enabled team areas property.
static java.lang.String	EXTERNAL_MANAGER_PROPERTY The external manager property.
static java.lang.String	EXTERNAL_REPOSITORY_PROPERTY The external repository property.
static java.lang.String	EXTERNAL_TYPE_NAME_PROPERTY The external type name property.
static java.lang.String	ITEM_MANAGER_PROPERTY The item manager property.
static IItemType	ITEM_TYPE SyncRule item type.
static java.lang.String	MAX_CYCLE_COUNT_PROPERTY The maximum cycle count property.
static java.lang.String	NAME_PROPERTY The name property.
static java.lang.String	PROJECT_AREA_PROPERTY The project area property.
static java.lang.String	PROPERTY_MAPPINGS_PROPERTY The property mappings property.
static java.lang.String	SYNC_ALL_ITEM_STATES_PROPERTY The sync all item states property.
static java.lang.String	SYNC_INFO_PROPERTY The sync info property, for getting the last search time and synchronization enabled flags.
static java.lang.String	SYNC_ITEM_TYPE_PROPERTY The sync item type property.
static java.lang.String	SYNC_ITEM_TYPE_QUALIFIER_PROPERTY The sync item type qualifier property.

Fields inherited from interface com.ibm.team.repository.common.IAuditable

MERGE_PREDECESSOR_STATE_PROPERTY, PREDECESSOR_STATE_PROPERTY

Fields inherited from interface com.ibm.team.repository.common.IItem

CONTEXT_ID_PROPERTY, ITEM_ID_PROPERTY, MAX_LARGE_STRING_BYTES, MAX_MEDIUM_STRING_BYTES, MAX_SMALL_STRING_BYTES, MODIFIED_BY_PROPERTY, MODIFIED_PROPERTY, STATE_ID_PROPERTY

Method Summary

Methods

Modifier and Type	Method and Description
IPropertyMapping[]	addCandidatePropertyMappings(ITypeInfoDTO itemTypeInfo, ITypeInfoDTO externalTypeInfo, boolean mappedOnly) Add mappings for the properties of item and/or external types.
IValueMapping[]	addCandidateValueMappings(IPropertyMapping propertyMapping, IPropertyInfoDTO itemPropertyInfo, IPropertyInfoDTO externalPropertyInfo, boolean mappedOnly) Add mappings for the possible values of an item and/or external property.
void	addPropertyMappings(IPropertyMapping[] mappings) Add property mappings to the current set of mappings for this synchronization rule.
void	exportDefinition(java.io.Writer output) Export an external definition of this synchronization rule.
java.util.List<ITeamAreaHandle>	getEnabledTeamAreas() Get any team areas that have been explicitly enabled for outgoing synchronization of unconnected artifacts.
IPropertyMapping	getExternalIdentifierPropertyMapping() Get the mapping for a property that is used as an identifier for finding existing external objects, if any.
java.lang.String	getExternalManager() Get the name of the external manager (if any) to use when fetching, creating, or updating external objects.
IPropertyMapping	getExternalModifierPropertyMapping() Get the mapping for a property that is used to identify the user that was responsible for the external object modifications that a particular external state represents.
IPropertyMapping	getExternalPropertyMapping(java.lang.String externalPropertyName) Get the mapping for a particular external property, if one exists.
IExternalRepositoryConnectionHandle	getExternalRepository() Get any external repository connection info needed for the external objects covered by this synchronization rule.
java.lang.String	getExternalTypeName() Get the external object type name this synchronization rule applies to, if any.
IPropertyMapping	getItemIdentifierPropertyMapping() Get the mapping for a property that is used as an identifier for finding existing Jazz items, if any.
java.lang.String	getItemManager() Get the name of the item manager (if any) to use when fetching, creating, or updating Jazz items.
IPropertyMapping	getItemPropertyMapping(java.lang.String itemPropertyName) Get the mapping for a particular item property, if one exists.
int	getMaxCycleCount() Get the cycle count limit for this synchronization rule.
java.lang.String	getName() Get the name of this synchronization rule.
IProjectAreaHandle	getProjectArea() Get the project area that the synchronization rule is associated with.
java.util.List	getPropertyMappings() Get the property mappings for this synchronization rule.
java.lang.String	getQualifiedSyncItemTypeName() Get the name of the Jazz item type that this synchronization rule applies to, in the form "namespace.name".
IItemType	getSyncItemType() Get the Jazz item type that this synchronization rule applies to, if any.
java.lang.String	getSyncItemTypeQualifier() Get any further qualification of the item type that this synchronization rule applies to, if any.
void	importDefinition(java.io.Reader input) Import an external definition of a synchronization rule into this object.
boolean	isSyncAllItemStates() Determine whether all item states should be synchronized out to an external object.
void	setExternalManager(java.lang.String value) Set the name of the external manager.
void	setExternalRepository(IExternalRepositoryConnectionHandle externalConnectionHandle) Associate or unassociate external repository connection info with this synchronization rule.
void	setExternalTypeName(java.lang.String typeName) Set the external object type name that this synchronization rule applies to.
void	setItemManager(java.lang.String value) Set the name of the item manager.
void	setMaxCycleCount(int value) Set the cycle count limit for this sychronization rule.
void	setName(java.lang.String name) Set the name of this synchronization rule.
void	setProjectArea(IProjectAreaHandle projectAreaHandle) Set the project area that this synchronization rule should be associated with.
void	setPropertyMappings(IPropertyMapping[] mappings) Set the property mappings for this synchronization rule, completely replacing any existing mappings.
void	setQualifiedSyncItemTypeName(java.lang.String qualifiedName) Set the type of Jazz item that this synchronization rule applies to, using a qualified name of the form "namespace.name".
void	setSyncAllItemStates(boolean syncAll) Set whether all item states of an item with history should be synchronized out to an external object.
void	setSyncItemType(IItemType value) Set the type of Jazz item that this synchronization rule applies to.
void	setSyncItemType(java.lang.String namespace, java.lang.String name) Set the type of Jazz item that this synchronization rule applies to, using the namespace and name of the item type.
void	setSyncItemTypeQualifier(java.lang.String qualifier) Set an item type qualifier to restrict this synchronization rule to apply to only certain items of the type identified by getSyncItemType().

Methods inherited from interface com.ibm.team.repository.common.IAuditable

getMergePredecessorState, getPredecessorState

Methods inherited from interface com.ibm.team.repository.common.IManagedItem

isNewItem

Methods inherited from interface com.ibm.team.repository.common.IItem

getContextId, getItemHandle, getModifiedBy, getRedactedCopy, getRequestedModified, getRequestedStateId, getStateHandle, getWorkingCopy, hasHistory, isComplete, isPropertySet, isRedactedCopy, isWorkingCopy, modified, setContextId, setRequestedModified, setRequestedStateId

Methods inherited from interface com.ibm.team.repository.common.IItemHandle

equals, getAdapter, getFullState, getItemId, getItemType, getOrigin, getStateId, hasFullState, hasStateId, isAuditable, isConfigurationAware, isImmutable, isSimple, isUnmanaged, makeImmutable, protect, sameItemId, sameStateId, size

Field Detail

ITEM_TYPE

static final IItemType ITEM_TYPE

SyncRule item type.

NAME_PROPERTY

static final java.lang.String NAME_PROPERTY

The name property.

See Also:

getName()

EXTERNAL_TYPE_NAME_PROPERTY

static final java.lang.String EXTERNAL_TYPE_NAME_PROPERTY

The external type name property.

See Also:

getExternalTypeName()

SYNC_ITEM_TYPE_PROPERTY

static final java.lang.String SYNC_ITEM_TYPE_PROPERTY

The sync item type property.

See Also:

getSyncItemType()

SYNC_ITEM_TYPE_QUALIFIER_PROPERTY

static final java.lang.String SYNC_ITEM_TYPE_QUALIFIER_PROPERTY

The sync item type qualifier property.

See Also:

getSyncItemTypeQualifier()

PROPERTY_MAPPINGS_PROPERTY

static final java.lang.String PROPERTY_MAPPINGS_PROPERTY

The property mappings property.

See Also:

getPropertyMappings()

ITEM_MANAGER_PROPERTY

static final java.lang.String ITEM_MANAGER_PROPERTY

The item manager property.

See Also:

getItemManager()

EXTERNAL_MANAGER_PROPERTY

static final java.lang.String EXTERNAL_MANAGER_PROPERTY

The external manager property.

See Also:

getExternalManager()

PROJECT_AREA_PROPERTY

static final java.lang.String PROJECT_AREA_PROPERTY

The project area property.

See Also:

getProjectArea()

MAX_CYCLE_COUNT_PROPERTY

static final java.lang.String MAX_CYCLE_COUNT_PROPERTY

The maximum cycle count property.

See Also:

getMaxCycleCount()

SYNC_INFO_PROPERTY

static final java.lang.String SYNC_INFO_PROPERTY

The sync info property, for getting the last search time and synchronization enabled flags.

SYNC_ALL_ITEM_STATES_PROPERTY

static final java.lang.String SYNC_ALL_ITEM_STATES_PROPERTY

The sync all item states property.

See Also:

isSyncAllItemStates()

ENABLED_TEAM_AREAS_PROPERTY

static final java.lang.String ENABLED_TEAM_AREAS_PROPERTY

The enabled team areas property.

See Also:

getEnabledTeamAreas()

EXTERNAL_REPOSITORY_PROPERTY

static final java.lang.String EXTERNAL_REPOSITORY_PROPERTY

The external repository property.

See Also:

getExternalRepository()

Method Detail

getName

java.lang.String getName()

Get the name of this synchronization rule.

Returns:

the sync rule name

setName

void setName(java.lang.String name)

Set the name of this synchronization rule. This name must be globally unique (within the repository); it serves as the identifier of the synchronization rule.

Parameters:

value - the sync rule name; never null

getExternalTypeName

java.lang.String getExternalTypeName()

Get the external object type name this synchronization rule applies to, if any. If a single external object manager can handle multiple types of objects, then it may require identification of the type that a particular synchronization rule applies to.

Returns:

the external type name that this synchronization rule applies to; may be null or the empty string if unspecified

setExternalTypeName

void setExternalTypeName(java.lang.String typeName)

Set the external object type name that this synchronization rule applies to. This property is optional, and is only required if the external object manager used for this synchronization rule needs it.

Parameters:

typeName - the external object type name that this synchronization rule applies to; may be null or the empty string to clear this property

getSyncItemType

IItemType getSyncItemType()

Get the Jazz item type that this synchronization rule applies to, if any.

Returns:

the type of Jazz item that is synchronized with an external object, or null if there is no synchronization, just replication

getQualifiedSyncItemTypeName

java.lang.String getQualifiedSyncItemTypeName()

Get the name of the Jazz item type that this synchronization rule applies to, in the form "namespace.name".

Returns:

the qualified name of the Jazz item that this synchronization rule applies to, or null if there is no synchronization, just replication

Since:

0.7

setSyncItemType

void setSyncItemType(IItemType value)

Set the type of Jazz item that this synchronization rule applies to.

Parameters:

value - the type of Jazz item that is synchronized with an external object, or null if no synchronization occurs

setQualifiedSyncItemTypeName

void setQualifiedSyncItemTypeName(java.lang.String qualifiedName)

Set the type of Jazz item that this synchronization rule applies to, using a qualified name of the form "namespace.name".

Parameters:

qualifiedName - the qualified name of the item type, or null to clear the item type

Since:

0.7

setSyncItemType

void setSyncItemType(java.lang.String namespace,
                   java.lang.String name)

Set the type of Jazz item that this synchronization rule applies to, using the namespace and name of the item type.

Parameters:

namespace - the namespace for the item type, or null to clear the item type

name - the simple name of the item type, or null to clear the item type

Since:

0.7

getSyncItemTypeQualifier

java.lang.String getSyncItemTypeQualifier()

Get any further qualification of the item type that this synchronization rule applies to, if any. An item manager can distinguish between different "sub-types" of an item type by defining some sort of qualifier for an item (e.g. the value of a certain property). If this value is null or empty, then the synchronization rule applies to all items of the type identified by getSyncItemType().

Returns:

any further qualifier used by an item manager to distinguish between "sub-types" of an item; null or empty if none

setSyncItemTypeQualifier

void setSyncItemTypeQualifier(java.lang.String qualifier)

Set an item type qualifier to restrict this synchronization rule to apply to only certain items of the type identified by getSyncItemType().

Parameters:

qualifier - the qualifier for selecting items that this synchronization rule will apply to; null or empty for no qualification

See Also:

getSyncItemType()

isSyncAllItemStates

boolean isSyncAllItemStates()

Determine whether all item states should be synchronized out to an external object. If false, only the current state of an item is considered when changes are detected for outgoing synchronization. If true, and the item maintains history, then all states created since the last time the item was synchronized out (all existing state the first time it is synchronized) are "replayed" to the external object.

The default value for this property is false.

Returns:

true if all states of an item with history should be synchronized out to an external object, false if only the current state should be synchronized out

setSyncAllItemStates

void setSyncAllItemStates(boolean syncAll)

Set whether all item states of an item with history should be synchronized out to an external object.

Parameters:

syncAll - true to synchronize all item state out to an external object, false to synchronize only the current state

See Also:

isSyncAllItemStates()

getPropertyMappings

java.util.List getPropertyMappings()

Get the property mappings for this synchronization rule. Each list element is of type #IPropertyMapping.

Returns:

the list of property mappings; never null, but may be empty

getItemPropertyMapping

IPropertyMapping getItemPropertyMapping(java.lang.String itemPropertyName)

Get the mapping for a particular item property, if one exists.

Parameters:

itemPropertyName - the name of the item property

Returns:

the mapping for the item property, or null if none was found

getExternalPropertyMapping

IPropertyMapping getExternalPropertyMapping(java.lang.String externalPropertyName)

Get the mapping for a particular external property, if one exists.

Parameters:

externalPropertyName - the name of the external property

Returns:

the mapping for the external property, or null if none was found

getItemIdentifierPropertyMapping

IPropertyMapping getItemIdentifierPropertyMapping()

Get the mapping for a property that is used as an identifier for finding existing Jazz items, if any.

Returns:

the mapping that is marked as an item identifier property, if any, or null if none

Since:

0.6

getExternalIdentifierPropertyMapping

IPropertyMapping getExternalIdentifierPropertyMapping()

Get the mapping for a property that is used as an identifier for finding existing external objects, if any.

Returns:

the mapping that is marked as an external identifier property, if any, or null if none

Since:

0.6

getExternalModifierPropertyMapping

IPropertyMapping getExternalModifierPropertyMapping()

Get the mapping for a property that is used to identify the user that was responsible for the external object modifications that a particular external state represents.

Returns:

the mapping that is marked as an external modifier property, if any, or null if none

Since:

0.6

setPropertyMappings

void setPropertyMappings(IPropertyMapping[] mappings)

Set the property mappings for this synchronization rule, completely replacing any existing mappings.

Parameters:

mappings - new list of property mappings; never null

addPropertyMappings

void addPropertyMappings(IPropertyMapping[] mappings)

Add property mappings to the current set of mappings for this synchronization rule. Any existing mappings that have the same external property name as a mapping in this list are replaced.

Parameters:

mappings - array of mappings to add/replace; never null

addCandidatePropertyMappings

IPropertyMapping[] addCandidatePropertyMappings(ITypeInfoDTO itemTypeInfo,
                                              ITypeInfoDTO externalTypeInfo,
                                              boolean mappedOnly)

Add mappings for the properties of item and/or external types. If both item type and external type information is provided, then similarly-named properties will be mapped to each other. In this case, if the mappedOnly argument is true, only properties that could be mapped are added, otherwise all item properties are added, whether they could be mapped or not. If no item type info is supplied, then all external properties are added.

Parameters:

itemTypeInfo - information about the item type's properties, or null if item type info not known

externalTypeInfo - information about the external type's properties; must not be null

mappedOnly - if itemTypeInfo is not null, then true means to add only item properties that could be mapped to external properties, and false means to add all item properties

Returns:

the new mappings that were added; never null; may be empty

Since:

0.7

addCandidateValueMappings

IValueMapping[] addCandidateValueMappings(IPropertyMapping propertyMapping,
                                        IPropertyInfoDTO itemPropertyInfo,
                                        IPropertyInfoDTO externalPropertyInfo,
                                        boolean mappedOnly)

Add mappings for the possible values of an item and/or external property. If both item and external property information is provided, then similarly-named values will be mapped to each other. In this case, if the mappedOnly argument is true, only values that could be mapped are added, otherwise all item values are added, whether they could be mapped or not. If no item property info is supplied, then all external values are added.

Parameters:

propertyMapping - the property mappings to add value mappings to

itemPropertyInfo - information about the allowed property values, or null if item property info not known

externalPropertyInfo - information about the external property values; must not be null

mappedOnly - if itemPropertyInfo is not null, then true means to add only item properties that could be mapped to external properties, and false means to add all item properties

Returns:

the new mappings that were added; never null; may be empty

Since:

0.7

getItemManager

java.lang.String getItemManager()

Get the name of the item manager (if any) to use when fetching, creating, or updating Jazz items. The item manager implements a generic interface to get and set properties, and save items of the type identified by this synchronization rule.

Returns:

name of the item manager extension, may be null or the empty string if no incoming synchronization is configured

setItemManager

void setItemManager(java.lang.String value)

Set the name of the item manager. The name must identify an extension for the item manager extension point in the Interop service plug-in.

Parameters:

value - the name of the item manager; null or the empty string if there is no incoming synchronization

getExternalManager

java.lang.String getExternalManager()

Get the name of the external manager (if any) to use when fetching, creating, or updating external objects. The external manager implements a generic interface to get and set properties, and fetch and save external objects.

Returns:

name of the external manager extension, may be null or the empty string if no outgoing synchronization is configured

setExternalManager

void setExternalManager(java.lang.String value)

Set the name of the external manager. The name must identify an extension for the external manager extension point in the Interop service plug-in.

Parameters:

value - the name of the external manager; null or the empty string if there is no outgoing synchronization

getMaxCycleCount

int getMaxCycleCount()

Get the cycle count limit for this synchronization rule. The limit is the number of incoming/outgoing synchronization cycles that will cause the proxy status to be set to IExternalProxy#STATUS_CYCLE, so it is one greater than the number of permitted cycles. The default value is 0, which allows 1 cycle.

Returns:

the cycle limit count

setMaxCycleCount

void setMaxCycleCount(int value)

Set the cycle count limit for this sychronization rule. See getMaxCycleCount() for a description of the value.

Parameters:

value - the new cycle count limit; must be non-negative

getProjectArea

IProjectAreaHandle getProjectArea()

Get the project area that the synchronization rule is associated with.

Returns:

handle for the project area; may be null

setProjectArea

void setProjectArea(IProjectAreaHandle projectAreaHandle)

Set the project area that this synchronization rule should be associated with. The project area association is used when determining what process settings to use during synchronization. (Any process area that the item being synchronized is associated with may also be used.)

Parameters:

projectAreaHandle - handle for the project area, or null to unassociate the synchronization rule with any project area

getEnabledTeamAreas

java.util.List<ITeamAreaHandle> getEnabledTeamAreas()

Get any team areas that have been explicitly enabled for outgoing synchronization of unconnected artifacts. If there are no explicitly enabled team areas, all team areas in the project area associated with this synchronization rule are considered to be enabled.

This affects whether external connections are attempted for artifacts that currently have no external connection. When an unconnected artifact is created or modified, and there is a synchronization rule that applies to the artifact in the project area associated with the artifact, then if the synchronization rule has any explicitly enabled team areas, the artifact must also be associated with one of the team areas in order to be considered for connection to an external object.

To modify the list of explicitly enabled team areas, use this method to retrieve the list, then operate on the list directly.

Returns:

any team areas explicitly enabled for outgoing synchronization of unconnected artifacts; may be empty; never null

Since:

0.6

getExternalRepository

IExternalRepositoryConnectionHandle getExternalRepository()

Get any external repository connection info needed for the external objects covered by this synchronization rule. If the external manager requires connection info in order to access the external repository, then the synchronization rule must reference that connection info.

Returns:

any external repository connection info; may be null

Since:

0.6

setExternalRepository

void setExternalRepository(IExternalRepositoryConnectionHandle externalConnectionHandle)

Associate or unassociate external repository connection info with this synchronization rule.

Parameters:

externalConnectionHandle - handle for an IExternalRepositoryConnection item, or null to clear any reference

Since:

0.6

See Also:

getExternalRepository()

importDefinition

void importDefinition(java.io.Reader input)
                      throws TeamRepositoryException

Import an external definition of a synchronization rule into this object. This object must be a new item or a working copy of an existing item. It can be saved after the import.

The external definition format is XML, with the schema defined in the schema/syncrule.xsd file. Note that a definition need not be complete; most elements are optional. Whatever properties are present in the definition will be applied to this object, so this is really just a way of setting properties.

Note that if the input is coming from byte-oriented media, since UTF-8 encoding is assumed, the input Reader must be configured to use the UTF-8 character set for decoding bytes into characters.

Parameters:

input - a reader for the source of the imported definition

Throws:

TeamRepositoryException - if the definition is invalid

Since:

0.6

exportDefinition

void exportDefinition(java.io.Writer output)
                      throws TeamRepositoryException

Export an external definition of this synchronization rule.

The external definition format is XML, with the schema defined in the schema/syncrule.xsd file.

Note that if the output is going to byte-oriented media, since UTF-8 encoding is assumed, the output Writer must be configured to use the UTF-8 character set for encoding characters into bytes.

Parameters:

output - a writer for the destination of the exported definition

Throws:

TeamRepositoryException - if there is an output error

Since:

0.6