org.azyva.dragom.model.plugin

Interface ScmPlugin

All Superinterfaces:

ModulePlugin, NodePlugin

public interface ScmPlugin
extends ModulePlugin

Provides the abstractions required by Dragom for accessing a Module source code and other information in an SCM.

Author:

David Raymond

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ScmPlugin.BaseVersion Information about the base Version of a Version.
static class	ScmPlugin.Commit Represents a commit.
static class	ScmPlugin.CommitPaging Controls commit paging for getListCommit(org.azyva.dragom.model.Version, org.azyva.dragom.model.plugin.ScmPlugin.CommitPaging, java.util.EnumSet<org.azyva.dragom.model.plugin.ScmPlugin.GetListCommitFlag>) or getListCommitDiverge(org.azyva.dragom.model.Version, org.azyva.dragom.model.Version, org.azyva.dragom.model.plugin.ScmPlugin.CommitPaging, java.util.EnumSet<org.azyva.dragom.model.plugin.ScmPlugin.GetListCommitFlag>).
static class	ScmPlugin.GetListCommitFlag Indicates what ScmPlugin.Commit information to include for getListCommit(org.azyva.dragom.model.Version, org.azyva.dragom.model.plugin.ScmPlugin.CommitPaging, java.util.EnumSet<org.azyva.dragom.model.plugin.ScmPlugin.GetListCommitFlag>) or getListCommitDiverge(org.azyva.dragom.model.Version, org.azyva.dragom.model.Version, org.azyva.dragom.model.plugin.ScmPlugin.CommitPaging, java.util.EnumSet<org.azyva.dragom.model.plugin.ScmPlugin.GetListCommitFlag>).
static class	ScmPlugin.IsSyncFlag Flags that can be passed to isSync.
static class	ScmPlugin.MergeResult Merge results.

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMMIT_ATTR_EQUIVALENT_STATIC_VERSION Commit attribute to store the equivalent static Version associated with a commit.
static String	COMMIT_ATTR_REFERENCE_VERSION_CHANGE Commit attribute indicating that the commit changes the Version or ArtifactVersion of a reference in the Module.
static String	COMMIT_ATTR_VERSION_CHANGE Commit attribute indicating that the commit changes the ArtifactVersion of the Module.
static String	VERSION_ATTR_PROJECT_CODE Version attribute specifying the project code associated with a Version.

Method Summary

Modifier and Type	Method and Description
void	checkout(Version version, Path pathModuleWorkspace) Checks out the source code of a Version of a Module in a directory.
Path	checkoutSystem(Version version) Checks out the source code of a Version of a Module for Dragom's use.
void	commit(Path pathModuleWorkspace, String message, Map<String,String> mapCommitAttr) Commits changes to the source code of the Module.
void	createTempDynamicVersion(Path pathModuleWorkspace) Creates a temporary dynamic Version.
void	createVersion(Path pathModuleWorkspace, Version versionTarget, Map<String,String> mapVersionAttr, boolean indSwitch) Creates a Version of the Module.
ScmPlugin.BaseVersion	getBaseVersion(Version version) Gets the base Version of a given Version of the Module.
Version	getDefaultVersion()
List<ScmPlugin.Commit>	getListCommit(Version version, ScmPlugin.CommitPaging commitPaging, EnumSet<ScmPlugin.GetListCommitFlag> enumSetGetListCommitFlag) Gets the list of Commits for a Version.
List<ScmPlugin.Commit>	getListCommitDiverge(Version versionSrc, Version versionDest, ScmPlugin.CommitPaging commitPaging, EnumSet<ScmPlugin.GetListCommitFlag> enumSetGetListCommitFlag) Gets the list of ScmPlugin.Commit's reachable from some Version but not from some other Version.
List<Version>	getListVersionStatic()
Map<String,String>	getMapVersionAttr(Version version) Returns the attributes of a Version.
String	getScmType()
String	getScmUrl(Path pathModuleWorkspace) Returns the URL of the Module within the SCM.
Version	getVersion(Path pathModuleWorkspace) Returns the Version of the Module in a directory.
boolean	isModuleExists() Indicates if the Module exists in the SCM.
boolean	isSync(Path pathModuleWorkspace, EnumSet<ScmPlugin.IsSyncFlag> enumSetIsSyncFlag) Verifies if the source code of the Module is synchronized with the SCM.
boolean	isTempDynamicVersion(Version versionBase) Verifies if there is a temporary dynamic Version with the specified Version as its base.
boolean	isVersionExists(Version version) Verifies if a Version of a Module exists.
ScmPlugin.MergeResult	merge(Path pathModuleWorkspace, Version versionSrc, String message) Merges a Version of a Module into the current Version.
ScmPlugin.MergeResult	mergeExcludeCommits(Path pathModuleWorkspace, Version versionSrc, List<ScmPlugin.Commit> listCommitExclude, String message) Merges a Version of a Module into the current Version, excluding a List of Commit's.
void	releaseTempDynamicVersion(Path pathModuleWorkspace) Releases the temporary dynamic Version of the Module.
ScmPlugin.MergeResult	replace(Path pathModuleWorkspace, Version versionSrc, String message) Replaces the current Version of a Module with another.
void	switchVersion(Path pathModuleWorkspace, Version version) Changes the Version of a Module to another Version.
boolean	update(Path pathModuleWorkspace) Updates the source code of the Module from the SCM.

Methods inherited from interface org.azyva.dragom.model.plugin.ModulePlugin

getModule

Methods inherited from interface org.azyva.dragom.model.plugin.NodePlugin

getNode

Field Detail

COMMIT_ATTR_EQUIVALENT_STATIC_VERSION

static final String COMMIT_ATTR_EQUIVALENT_STATIC_VERSION

Commit attribute to store the equivalent static Version associated with a commit. Generally used on commits that revert the adjustment to the ArtifactVersion after the new static version was created.

This is often not directly used by ScmPlugin implementations, but this is still the most logical place to declare this constant.

See Also:

Constant Field Values

COMMIT_ATTR_VERSION_CHANGE

static final String COMMIT_ATTR_VERSION_CHANGE

Commit attribute indicating that the commit changes the ArtifactVersion of the Module. The possible values are true and false, although if a commit does not change the ArtifactVersion this attribute will generally not be included.

This is often not directly used by ScmPlugin implementations, but this is still the most logical place to declare this constant.

See Also:

Constant Field Values

COMMIT_ATTR_REFERENCE_VERSION_CHANGE

static final String COMMIT_ATTR_REFERENCE_VERSION_CHANGE

Commit attribute indicating that the commit changes the Version or ArtifactVersion of a reference in the Module. The possible values are true and false, although if a commit does not change the Version or ArtifactVersion of a reference this attribute will generally not be included.

This is often not directly used by ScmPlugin implementations, but this is still the most logical place to declare this constant.

See Also:

Constant Field Values

VERSION_ATTR_PROJECT_CODE

static final String VERSION_ATTR_PROJECT_CODE

Version attribute specifying the project code associated with a Version.

See RootModuleVersionJobAbstractImpl#RUNTIME_PROPERTY_PROJECT_CODE from dragom-core.

See Also:

Constant Field Values

Method Detail

isModuleExists

boolean isModuleExists()

Indicates if the Module exists in the SCM.

Can be used on a temporary Module (whose parent has not been updated yet to refer to it) in the process of verifying if a dynamically created Module exists. See UndefinedDescendantNodeManagerPlugin.

Returns:

See description.

getDefaultVersion

Version getDefaultVersion()

Returns:

Default Version.

checkout

void checkout(Version version,
              Path pathModuleWorkspace)

Checks out the source code of a Version of a Module in a directory.

pathModuleWorkspace should correspond to a WorkspaceDirUserModuleVersion.

Parameters:

version - Version.

pathModuleWorkspace - Path of the directory.

checkoutSystem

Path checkoutSystem(Version version)

Checks out the source code of a Version of a Module for Dragom's use.

The Path should correspond to a WorkspaceDirSystemModule.

Parameters:

version - Version.

Returns:

Path containing the checked out source code.

isVersionExists

boolean isVersionExists(Version version)

Verifies if a Version of a Module exists.

Parameters:

version - Version.

Returns:

See description.

isSync

boolean isSync(Path pathModuleWorkspace,
               EnumSet<ScmPlugin.IsSyncFlag> enumSetIsSyncFlag)

Verifies if the source code of the Module is synchronized with the SCM.

Parameters:

pathModuleWorkspace - Path to the Module.

enumSetIsSyncFlag - EnumSet of IsSyncFlag specifying the synchronization status of which types of changes to verify.

Returns:

See description.

update

boolean update(Path pathModuleWorkspace)

Updates the source code of the Module from the SCM.

Parameters:

pathModuleWorkspace - Path to the Module.

Returns:

Indicates if the update was successful, or if merge conflicts occurred.

getVersion

Version getVersion(Path pathModuleWorkspace)

Returns the Version of the Module in a directory.

Parameters:

pathModuleWorkspace - Path to the Module.

Returns:

See description.

getListCommit

List<ScmPlugin.Commit> getListCommit(Version version,
                                     ScmPlugin.CommitPaging commitPaging,
                                     EnumSet<ScmPlugin.GetListCommitFlag> enumSetGetListCommitFlag)

Gets the list of Commits for a Version.

Enumeration stops at the first commit after creation of the Version.

If Version is static, the commits enumerated are those of the dynamic Version from which the static version was created, up to the first commit after the creation of that base Version.

Parameters:

version - Version.

commitPaging - CommitPaging information passed and returned. Can be null in which case all Commit are returned.

enumSetGetListCommitFlag - EnumSet of GetListCommitFlag. Can be null.

Returns:

See description.

getListCommitDiverge

List<ScmPlugin.Commit> getListCommitDiverge(Version versionSrc,
                                            Version versionDest,
                                            ScmPlugin.CommitPaging commitPaging,
                                            EnumSet<ScmPlugin.GetListCommitFlag> enumSetGetListCommitFlag)

Gets the list of ScmPlugin.Commit's reachable from some Version but not from some other Version.

Parameters:

versionSrc - Version for which the Commit's must be returned.

versionDest - Version whose Commit's must be excluded.

commitPaging - ScmPlugin.CommitPaging information passed and returned. Can be null in which case all Commit are returned.

enumSetGetListCommitFlag - EnumSet of GetListCommitFlag. Can be null.

Returns:

See description.

getBaseVersion

ScmPlugin.BaseVersion getBaseVersion(Version version)

Gets the base Version of a given Version of the Module.

Parameters:

version - Verison.

Returns:

See description.

getListVersionStatic

List<Version> getListVersionStatic()

Returns:

List of all static Version of the module.

switchVersion

void switchVersion(Path pathModuleWorkspace,
                   Version version)

Changes the Version of a Module to another Version.

Parameters:

pathModuleWorkspace - Path to the Module.

version - Version to switch to.

createVersion

void createVersion(Path pathModuleWorkspace,
                   Version versionTarget,
                   Map<String,String> mapVersionAttr,
                   boolean indSwitch)

Creates a Version of the Module.

Parameters:

pathModuleWorkspace - Path to the Module.

versionTarget - New Version.

mapVersionAttr - Version attributes.

indSwitch - Indicates to switch to the new Version.

getMapVersionAttr

Map<String,String> getMapVersionAttr(Version version)

Returns the attributes of a Version.

Parameters:

version - Version.

Returns:

See description.

createTempDynamicVersion

void createTempDynamicVersion(Path pathModuleWorkspace)

Creates a temporary dynamic Version.

The actual Version is not provided to the caller, but the Module is switched to that Version.

When a temporary dynamic Version is created, the Module workspace becomes in a special state which changes the behavior of some methods. This should be considered temporary and the caller should release it as soon as possible. At the very least it should be released before the tool completes. releaseTempDynamicVersion(java.nio.file.Path) and createVersion(java.nio.file.Path, org.azyva.dragom.model.Version, java.util.Map<java.lang.String, java.lang.String>, boolean) can be used for that purpose.

While a temporary dynamic Version is created, the caller should restrict itself to:

• commit
• createVersion
• releaseTempDynamicVersion
• Other methods which do not consider or return the path to the Module in the workspace

Note that checkoutSystem cannot be called is a temporary dynamic Version is in effect since this would mean that a caller could get a hold on the path to the Module in the workspace and not be aware of the temporary dynamic Version context. If access to the path to the module in the workspace is required from various places, that path will need to be shared programmatically.

Whether or not temporary dynamic Versions are visible in the remote repository is not specified.

Temporary dynamic Versions must be regarded as a feature related to making changes to a Module, not as the creation of a Version in itself. When the new temporary dynamic Version is created, the workspace directory need not be synchronized. In particular, there can be local changes intended to be committed in the temporary dynamic Version once created.

The concept of temporary dynamic Version provides an abstraction for the facility in some SCM such as Git to work locally on some changes before committing them as a real Version. This is useful when performing a release where adjustments are required on a {ModuleVersion} before creating the release Version, but these changes must not be visible on the main dynamic Version from which the release is performed.

For SCM which do not support such concepts, it is up to the implementation to provide an equivalent behavior using, for exemple, regular branches, or to simply not support the operations related to temporary dynamic Versions, preventing the use of these features in tools.

Parameters:

pathModuleWorkspace - Path to the module within the workspaace.

isTempDynamicVersion

boolean isTempDynamicVersion(Version versionBase)

Verifies if there is a temporary dynamic Version with the specified Version as its base.

This can be used by callers to be aware of the existence of a temporary dynamic Version and adapt their behavior accordingly. However, callers that are not in the know and do not have a hold on the path to the module in workspace will not be able to obtain it as checkoutSystem(org.azyva.dragom.model.Version) cannot be used in that case.

Parameters:

versionBase - Base Version.

Returns:

See description.

releaseTempDynamicVersion

void releaseTempDynamicVersion(Path pathModuleWorkspace)

Releases the temporary dynamic Version of the Module.

Parameters:

pathModuleWorkspace - Path to the Module.

commit

void commit(Path pathModuleWorkspace,
            String message,
            Map<String,String> mapCommitAttr)

Commits changes to the source code of the Module.

Parameters:

pathModuleWorkspace - Path to the Module.

message - Commit message.

mapCommitAttr - Commit attributes. Can be null.

merge

ScmPlugin.MergeResult merge(Path pathModuleWorkspace,
                            Version versionSrc,
                            String message)

Merges a Version of a Module into the current Version.

Parameters:

pathModuleWorkspace - Path to the Module.

versionSrc - Version to merge.

message - Commit message. Can be null to let a default message be used.

Returns:

MergeResult.

mergeExcludeCommits

ScmPlugin.MergeResult mergeExcludeCommits(Path pathModuleWorkspace,
                                          Version versionSrc,
                                          List<ScmPlugin.Commit> listCommitExclude,
                                          String message)

Merges a Version of a Module into the current Version, excluding a List of Commit's.

Parameters:

pathModuleWorkspace - Path to the Module.

versionSrc - Version to merge.

listCommitExclude - List of Commit's to exclude.

message - Commit message. Can be null to let a default message be used.

Returns:

MergeResult.

replace

ScmPlugin.MergeResult replace(Path pathModuleWorkspace,
                              Version versionSrc,
                              String message)

Replaces the current Version of a Module with another.

This is similar to a merge but where we want to ignore what is in the current Version.

Parameters:

pathModuleWorkspace - Path to the Module.

versionSrc - Version to merge.

message - Commit message. Can be null to let a default message be used.

Returns:

MergeResult. MergeResult.CONFLICTS cannot be returned.

getScmType

String getScmType()

Returns:

SCM type.

getScmUrl

String getScmUrl(Path pathModuleWorkspace)

Returns the URL of the Module within the SCM.

Even for the same Module, its URL in the SCM may be different depending on the actual source code checked out, which is why the Path to the Module is specified. This can happen when the SCM allows forking Modules.

Parameters:

pathModuleWorkspace - Path to the Module.

Returns:

See description.