org.electrocodeogram.cpc.core.api.provider.cpcrepository
Interface ICPCRepositoryProvider

All Superinterfaces:

IProvider

public interface ICPCRepositoryProvider
extends IProvider

An ICPCRepositoryProvider provides a centralised remote storage service for CPC clone data which may be access concurrently from multiple CPC installations.

A typical use for a provider of this type is to store the current cpc data for a file in a central location, whenever it is committed into a source repository and to fetch the most up to date cpc data for a file whenever it is checked out, updated or merged.

Most methods of this API are likely to require remote calls. They can thus fail and are potentially long running.

NOTE: Any implementation must guarantee that concurrent calls to the put and get methods on this and other systems do not result in invalid data.

Author:

vw

See Also:

ICPCRevision

Method Summary

ICPCRevision	createRevision() Creates a new and empty ICPCRevision instance which can then be filled by the client.
ICPCRevision	getRevision(java.lang.String revisionId, java.lang.String cloneFileUuid) Retrieves the cpc data revision with the given revisionId for the ICloneFile with the given cloneFileUuid.
ICPCRevision	getRevision(java.lang.String revisionId, java.lang.String project, java.lang.String filePath) Retrieves the cpc data revision with the given revisionId for the ICloneFile with the given project and filePath location.
void	hintEndTransaction() This method must only be called if hintStartTransaction() was called.
void	hintStartTransaction() This method should be called by clients of this interface if it is expected that multiple repository operations will be done within a short period of time.
boolean	isAvailable() Checks whether this cpc repository is currently available.
boolean	purgeRevision(java.lang.String revisionId, java.lang.String cloneFileUuid) Tells the ICPCRepositoryProvider that the specified revision is no longer needed and can be deleted.
boolean	purgeRevision(java.lang.String revisionId, java.lang.String project, java.lang.String filePath) Tells the ICPCRepositoryProvider that the specified revision is no longer needed and can be deleted.
void	putRevision(ICPCRevision cpcRevision) Stores the given cpc data revision in the remote repository.

Methods inherited from interface org.electrocodeogram.cpc.core.api.provider.IProvider

getProviderName, toString

Method Detail

isAvailable

boolean isAvailable()

Checks whether this cpc repository is currently available.

This method will typically try to connect to a remote location and verify that there are no connectivity or version incompatibility issues which would prevent the normal use of this provider.

If this method returns false most other methods of this API are likely to throw an exception when used.
However return value of true does not guarantee that no exception will occur.

Returns:

true if the repository is ready for use, false if there are any conditions which prevent normal use.

putRevision

void putRevision(ICPCRevision cpcRevision)
                 throws CPCRepositoryException

Stores the given cpc data revision in the remote repository.
An exception will be thrown if the repository already contains an entry for that file with the same revision identifier.

Parameters:

cpcRevision - the cpc data revision to store, never null.

Throws:

CPCRepositoryException

getRevision

ICPCRevision getRevision(java.lang.String revisionId,
                         java.lang.String cloneFileUuid)
                         throws CPCRepositoryException

Retrieves the cpc data revision with the given revisionId for the ICloneFile with the given cloneFileUuid.

Parameters:

revisionId - the revision identifier to retrieve, never null.

cloneFileUuid - the ICloneObject.getUuid() value of the file to retrieve the data for, never null.

Returns:

a ICPCRevision or NULL if no such revision was found.

Throws:

CPCRepositoryException

getRevision

ICPCRevision getRevision(java.lang.String revisionId,
                         java.lang.String project,
                         java.lang.String filePath)
                         throws CPCRepositoryException

Retrieves the cpc data revision with the given revisionId for the ICloneFile with the given project and filePath location.

Parameters:

revisionId - the revision identifier to retrieve, never null.

project - the project name of the ICloneFile to retrieve the data for, never null.

filePath - the project relative path of the ICloneFile to retrieve the data for, never null.

Returns:

a ICPCRevision or NULL if no such revision was found.

Throws:

CPCRepositoryException

purgeRevision

boolean purgeRevision(java.lang.String revisionId,
                      java.lang.String cloneFileUuid)
                      throws CPCRepositoryException

Tells the ICPCRepositoryProvider that the specified revision is no longer needed and can be deleted.
The ICPCRepositoryProvider may not return a revision to any client once it has been marked for purging in this way.

Parameters:

revisionId - the revision identifier of the revision to purge, never null.

cloneFileUuid - cloneFileUuid the ICloneObject.getUuid() value of the file to purge the revision for, never null.

Returns:

true if such a revision was found and purged, false if no such revision existed.

Throws:

CPCRepositoryException

purgeRevision

boolean purgeRevision(java.lang.String revisionId,
                      java.lang.String project,
                      java.lang.String filePath)
                      throws CPCRepositoryException

Tells the ICPCRepositoryProvider that the specified revision is no longer needed and can be deleted.
The ICPCRepositoryProvider may not return a revision to any client once it has been marked for purging in this way.

Parameters:

revisionId - the revision identifier of the revision to purge, never null.

project - the project name of the ICloneFile to purge the data for, never null.

filePath - the project relative path of the ICloneFile to purge the data for, never null.

Returns:

true if such a revision was found and purged, false if no such revision existed.

Throws:

CPCRepositoryException

createRevision

ICPCRevision createRevision()

Creates a new and empty ICPCRevision instance which can then be filled by the client.

ICPCRevision instances must not be mixed between ICPCRepositoryProviders and a client may not use its own implementations.

Returns:

new and empty ICPCRevision instance, never null.

hintStartTransaction

void hintStartTransaction()
                          throws CPCRepositoryException

This method should be called by clients of this interface if it is expected that multiple repository operations will be done within a short period of time.

It is up to the implementation of this interface whether to make use of this additional information. The implementation may not rely on a call to this method. The visible behaviour of the implementation must not change depending on whether this method is called or not.

While calling this method is optional, a client must call hintEndTransaction() once it called this method.

NOTE: this method is only meant to improve performance. No transactional properties are guaranteed by this API.

A typical use of this method is the setup of some remote network connection.

Throws:

CPCRepositoryException

See Also:

hintEndTransaction()

hintEndTransaction

void hintEndTransaction()

This method must only be called if hintStartTransaction() was called. For each call to hintStartTransaction() there needs to be exactly one call to hintEndTransaction().

A typical use of this method is the shutdown of some remote network connection.

See Also:

hintStartTransaction()