diff --git a/core/src/main/java/pl/project13/core/AheadBehind.java b/core/src/main/java/pl/project13/core/AheadBehind.java index 11ed3a13..09bd4177 100644 --- a/core/src/main/java/pl/project13/core/AheadBehind.java +++ b/core/src/main/java/pl/project13/core/AheadBehind.java @@ -19,31 +19,64 @@ import java.util.Objects; +/** + * A local git repository can either be "ahead", or "behind" in the number of commits + * relative to the remote repository. This class tracks the amount of commits the local git repository + * is "behind", or "ahead" relative to it's remote. + */ public class AheadBehind { + /** + * Indication that we could not find a remote repository to calculate a "behind", or "ahead" relation. + */ public static final AheadBehind NO_REMOTE = AheadBehind.of("NO_REMOTE", "NO_REMOTE"); private final String ahead; private final String behind; + /** + * Constructor for a "AheadBehind"-object. + * @param ahead Number of commits the local repository is "ahead" in relation to it's remote. + * @param behind Number of commits the local repository is "behind" in relation to it's remote. + */ private AheadBehind(String ahead, String behind) { this.ahead = ahead; this.behind = behind; } + /** + * Constructor for a "AheadBehind"-object. + * @param ahead Number of commits the local repository is "ahead" in relation to it's remote. + * @param behind Number of commits the local repository is "behind" in relation to it's remote. + * + * @return a "AheadBehind"-object. + */ public static AheadBehind of(int ahead, int behind) { return new AheadBehind(String.valueOf(ahead), String.valueOf(behind)); } + /** + * Constructor for a "AheadBehind"-object. + * @param ahead Number of commits the local repository is "ahead" in relation to it's remote. + * @param behind Number of commits the local repository is "behind" in relation to it's remote. + * + * @return a "AheadBehind"-object. + */ public static AheadBehind of(String ahead, String behind) { return new AheadBehind(ahead, behind); } + /** + * @return Number of commits the local repository is "ahead" in relation to it's remote. + */ public String ahead() { return ahead; } + /** + * @return Number of commits the local repository is "behind" in relation to it's remote. + */ public String behind() { return behind; } diff --git a/core/src/main/java/pl/project13/core/CannotReadFileException.java b/core/src/main/java/pl/project13/core/CannotReadFileException.java index ec47d803..2a761c68 100644 --- a/core/src/main/java/pl/project13/core/CannotReadFileException.java +++ b/core/src/main/java/pl/project13/core/CannotReadFileException.java @@ -17,9 +17,20 @@ package pl.project13.core; +/** + * An exception to indicate that a required file could not be found. + */ public class CannotReadFileException extends Exception { private static final long serialVersionUID = -9080356227094128542L; + /** + * Constructs a new exception with the specified cause + * + * @param cause the cause (which is saved for later retrieval by the + * {@link Exception#getCause()} method). (A {@code null} value is + * permitted, and indicates that the cause is nonexistent or + * unknown.) + */ public CannotReadFileException(Throwable cause) { super(cause); } diff --git a/core/src/main/java/pl/project13/core/CommitIdGenerationMode.java b/core/src/main/java/pl/project13/core/CommitIdGenerationMode.java index 4ef7e858..34283406 100644 --- a/core/src/main/java/pl/project13/core/CommitIdGenerationMode.java +++ b/core/src/main/java/pl/project13/core/CommitIdGenerationMode.java @@ -17,7 +17,17 @@ package pl.project13.core; +/** + * An enum to indicate how the {@code git.commit.id} property should be generated. + * See https://github.com/ktoso/maven-git-commit-id-plugin/issues/211 for further details. + */ public enum CommitIdGenerationMode { + /** + * Indicator to generate a {@code git.commit.id.full} property + */ FULL, + /** + * Indicator to generate a {@code git.commit.id} property (default) + */ FLAT } diff --git a/core/src/main/java/pl/project13/core/GitCommitIdExecutionException.java b/core/src/main/java/pl/project13/core/GitCommitIdExecutionException.java index 0faa8581..fed6ceab 100644 --- a/core/src/main/java/pl/project13/core/GitCommitIdExecutionException.java +++ b/core/src/main/java/pl/project13/core/GitCommitIdExecutionException.java @@ -24,22 +24,63 @@ public class GitCommitIdExecutionException extends Exception { private static final long serialVersionUID = 4608506012492555968L; + /** + * Constructs a new exception + */ public GitCommitIdExecutionException() { super(); } + /** + * Constructs a new exception with the specified detail message. + * + * @param message the detail message. The detail message is saved for + * later retrieval by the {@link Exception#getMessage()} method. + */ public GitCommitIdExecutionException(String message) { super(message); } + /** + * Constructs a new exception with the specified detail message and + * cause. + * + * @param message the detail message (which is saved for later retrieval + * by the {@link Exception#getMessage()} method). + * @param cause the cause (which is saved for later retrieval by the + * {@link Exception#getCause()} method). (A {@code null} value is + * permitted, and indicates that the cause is nonexistent or + * unknown.) + */ public GitCommitIdExecutionException(String message, Throwable cause) { super(message, cause); } + /** + * Constructs a new exception with the specified cause + * + * @param cause the cause (which is saved for later retrieval by the + * {@link Exception#getCause()} method). (A {@code null} value is + * permitted, and indicates that the cause is nonexistent or + * unknown.) + */ public GitCommitIdExecutionException(Throwable cause) { super(cause); } + /** + * Constructs a new exception with the specified detail message, + * cause, suppression enabled or disabled, and writable stack + * trace enabled or disabled. + * + * @param message the detail message. + * @param cause the cause. (A {@code null} value is permitted, + * and indicates that the cause is nonexistent or unknown.) + * @param enableSuppression whether or not suppression is enabled + * or disabled + * @param writableStackTrace whether or not the stack trace should + * be writable + */ public GitCommitIdExecutionException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) { super(message, cause, enableSuppression, writableStackTrace); } diff --git a/core/src/main/java/pl/project13/core/GitCommitPropertyConstant.java b/core/src/main/java/pl/project13/core/GitCommitPropertyConstant.java index 63bee810..4d1e77f4 100644 --- a/core/src/main/java/pl/project13/core/GitCommitPropertyConstant.java +++ b/core/src/main/java/pl/project13/core/GitCommitPropertyConstant.java @@ -17,36 +17,132 @@ package pl.project13.core; +/** + * A class that represents all properties that may be generated by the plugin and exposed to maven. + */ public class GitCommitPropertyConstant { - // these properties will be exposed to maven + /** + * Represents the current branch name. Falls back to commit-id for detached HEAD. + */ public static final String BRANCH = "branch"; + /** + * Represents the count of commits that your local branch is ahead in perspective to the remote branch + * (usually the case when your local branch has committed changes that are not pushed yet to the remote branch). + */ public static final String LOCAL_BRANCH_AHEAD = "local.branch.ahead"; + /** + * Represents the count of commits that your local branch is behind in perspective to the remote branch + * (usually the case when there are commits in the remote branch that are not yet integrated into your local branch). + */ public static final String LOCAL_BRANCH_BEHIND = "local.branch.behind"; + /** + * A working tree is said to be "dirty" if it contains modifications + * which have not been committed to the current branch. + */ public static final String DIRTY = "dirty"; - // only one of the following two will be exposed, depending on the commitIdGenerationMode + /** + * Represents the commit’s SHA-1 hash. Note this is exchangeable with the git.commit.id.full property + * and might not be exposed. See {@code commitIdGenerationMode}. + */ public static final String COMMIT_ID_FLAT = "commit.id"; + /** + * Represents the commit’s SHA-1 hash. Note this is exchangeable with the git.commit.id property + * and might not be exposed. See {@code commitIdGenerationMode}. + */ public static final String COMMIT_ID_FULL = "commit.id.full"; + /** + * Represents the abbreviated (shorten version) commit hash. + */ public static final String COMMIT_ID_ABBREV = "commit.id.abbrev"; + /** + * Represents an object a human readable name based on a the commit (provides git describe for the given commit). + */ public static final String COMMIT_DESCRIBE = "commit.id.describe"; + /** + * Represents the same value as git.commit.id.describe, + * just with the git hash part removed (the g2414721 part from git describe). + */ public static final String COMMIT_SHORT_DESCRIBE = "commit.id.describe-short"; + /** + * Represents the git user name that is configured where the properties have been generated. + */ public static final String BUILD_AUTHOR_NAME = "build.user.name"; + /** + * Represents the git user eMail that is configured where the properties have been generated. + */ public static final String BUILD_AUTHOR_EMAIL = "build.user.email"; + /** + * Represents the (formatted) timestamp when the last build was executed. + * If written to the git.properties file represents the latest build time when that file was written / updated. + */ public static final String BUILD_TIME = "build.time"; + /** + * Represents the project version of the current maven project. + */ public static final String BUILD_VERSION = "build.version"; + /** + * Represents the hostname where the properties have been generated. + */ public static final String BUILD_HOST = "build.host"; + /** + * The git.build.number* variables are available on some hosted CIs and can be used to identify the + * "number" of the build. This represents a project specific build number. + */ public static final String BUILD_NUMBER = "build.number"; + /** + * The git.build.number* variables are available on some hosted CIs and can be used to identify the + * "number" of the build. This represents a system wide unique build number. + */ public static final String BUILD_NUMBER_UNIQUE = "build.number.unique"; + /** + * Represents the user name of the user who performed the commit. + */ public static final String COMMIT_AUTHOR_NAME = "commit.user.name"; + /** + * Represents the user eMail of the user who performed the commit. + */ public static final String COMMIT_AUTHOR_EMAIL = "commit.user.email"; + /** + * Represents the raw body (unwrapped subject and body) of the commit message. + */ public static final String COMMIT_MESSAGE_FULL = "commit.message.full"; + /** + * Represents the subject of the commit message - may not be suitable for filenames. + */ public static final String COMMIT_MESSAGE_SHORT = "commit.message.short"; + /** + * Represents the (formatted) time stamp when the commit has been performed. + */ public static final String COMMIT_TIME = "commit.time"; + /** + * Represents the (formatted) time stamp when the commit has been originally performed. + */ public static final String COMMIT_AUTHOR_TIME = "commit.author.time"; + /** + * Represents the (formatted) time stamp when the commit has been performed. + */ public static final String COMMIT_COMMITTER_TIME = "commit.committer.time"; + /** + * Represents the URL of the remote repository for the current git project. + */ public static final String REMOTE_ORIGIN_URL = "remote.origin.url"; + /** + * Represents a list of tags which contain the specified commit. + */ public static final String TAGS = "tags"; + /** + * Represents the name of the closest available tag. + * The closest tag may depend on your git describe config that may or may not take lightweight tags into consideration. + */ public static final String CLOSEST_TAG_NAME = "closest.tag.name"; + /** + * Represents the number of commits to the closest available tag. + * The closest tag may depend on your git describe config that may or may not take lightweight tags into consideration. + */ public static final String CLOSEST_TAG_COMMIT_COUNT = "closest.tag.commit.count"; + /** + * Represents the total count of all commits in the current repository. + */ public static final String TOTAL_COMMIT_COUNT = "total.commit.count"; } diff --git a/core/src/main/java/pl/project13/core/GitDataProvider.java b/core/src/main/java/pl/project13/core/GitDataProvider.java index 4de67810..52f03cfa 100644 --- a/core/src/main/java/pl/project13/core/GitDataProvider.java +++ b/core/src/main/java/pl/project13/core/GitDataProvider.java @@ -33,87 +33,223 @@ import java.util.concurrent.atomic.AtomicReference; import java.util.regex.Pattern; +/** + * An abstract Interface that dictates what functionality a {@code GitProvider} needs to fullfill. + * As of now this project implements two variants of a {@code GitProvider}. + * Namely {@link NativeGitProvider} which uses the native git binaries and + * {@link JGitProvider} which uses a java git implementation ({@code jgit}). + */ public abstract class GitDataProvider implements GitProvider { + /** + * Logging provider which will be used to log events. + */ @Nonnull protected final LoggerBridge log; + /** + * The {@code prefix} used for all generated properties. + */ protected String prefixDot; + /** + * The {@code commit abbreviation length} + */ protected int abbrevLength; + /** + * The {@code date format} for all generated properties. + */ protected String dateFormat; + /** + * The {@code date format time zone} for all generated properties. + */ protected String dateFormatTimeZone; + /** + * The {@link GitDescribeConfig}. + */ protected GitDescribeConfig gitDescribe = new GitDescribeConfig(); + /** + * The {@code git commit id generation mode}. + */ protected CommitIdGenerationMode commitIdGenerationMode; + /** + * Allow to tell the plugin what commit should be used as reference to generate the + * properties from. Defaults to {@code HEAD}. + */ protected String evaluateOnCommit; + /** + * When set to {@code true} this plugin will try to use the branch name from build environment. + * Set to {@code false} to use JGit/GIT to get current branch name which can be useful + * when using the JGitflow maven plugin. + * See https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/24 + */ protected boolean useBranchNameFromBuildEnvironment; + /** + * Can be used to exclude certain properties from being emitted (e.g. filter out properties + * that you *don't* want to expose). May be useful when you want to hide + * {@code git.remote.origin.url} (maybe because it contains your repo password?), + * or the email of the committer etc. + */ protected List excludeProperties; + /** + * Can be used to include only certain properties into the resulting file (e.g. include only + * properties that you *want* to expose). This feature was implemented to avoid big exclude + * properties tag when we only want very few specific properties. + * The inclusion rules, will be overruled by the exclude rules (e.g. you can write an + * inclusion rule that applies for multiple properties and then exclude a subset of them). + */ protected List includeOnlyProperties; + /** + * When set to {@code true}, the plugin will not try to contact any remote repositories. + * Any operations will only use the local state of the repo. + * If set to {@code false}, it will execute {@code git fetch} operations e.g. to determine the + * {@code ahead} and {@code behind} branch information. + */ protected boolean offline; + /** + * Constructor to encapsulates all references required to dertermine all git-data. + * @param log logging provider which will be used to log events + */ public GitDataProvider(@Nonnull LoggerBridge log) { this.log = log; } + /** + * Sets the {@link GitDescribeConfig} for the {@code GitProvider} + * @param gitDescribe The {@link GitDescribeConfig} + * @return The {@code GitProvider} with the corresponding {@link GitDescribeConfig}. + */ public GitDataProvider setGitDescribe(GitDescribeConfig gitDescribe) { this.gitDescribe = gitDescribe; return this; } + /** + * Sets the {@code prefix} used for all generated properties for the {@code GitProvider} + * @param prefixDot The {@code prefix} used for all generated properties + * @return The {@code GitProvider} with the corresponding {@code prefix}. + */ public GitDataProvider setPrefixDot(String prefixDot) { this.prefixDot = prefixDot; return this; } + /** + * Sets the {@code commit abbreviation length} for the {@code GitProvider} + * @param abbrevLength The {@code commit abbreviation length} + * @return The {@code GitProvider} with the corresponding {@code commit abbreviation length}. + */ public GitDataProvider setAbbrevLength(int abbrevLength) { this.abbrevLength = abbrevLength; return this; } + /** + * Sets the {@code date format} for all generated properties for the {@code GitProvider} + * @param dateFormat The {@code date format} for all generated properties. + * @return The {@code GitProvider} with the corresponding {@code date format}. + */ public GitDataProvider setDateFormat(String dateFormat) { this.dateFormat = dateFormat; return this; } + /** + * Sets the {@code git commit id generation mode} for the {@code GitProvider} + * @param commitIdGenerationMode The {@code git commit id generation mode} + * @return The {@code GitProvider} with the corresponding {@code git commit id generation mode}. + */ public GitDataProvider setCommitIdGenerationMode(CommitIdGenerationMode commitIdGenerationMode) { this.commitIdGenerationMode = commitIdGenerationMode; return this; } + /** + * Sets the {@code date format time zone} for all generated properties for the {@code GitProvider} + * @param dateFormatTimeZone The {@code date format time zone} for all generated properties. + * @return The {@code GitProvider} with the corresponding {@code date format time zone}. + */ public GitDataProvider setDateFormatTimeZone(String dateFormatTimeZone) { this.dateFormatTimeZone = dateFormatTimeZone; return this; } + /** + * Sets the Indicator if the branch name should be obtained from the build environment, or by the plugin. + * @param useBranchNameFromBuildEnvironment When set to {@code true} this plugin will try to use the branch name + * from build environment. Set to {@code false} to use JGit/GIT to get + * current branch name which can be useful when using the JGitflow + * maven plugin. + * See https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/24 + * + * @return The {@code GitProvider} with the corresponding Indicator set. + */ public GitDataProvider setUseBranchNameFromBuildEnvironment(boolean useBranchNameFromBuildEnvironment) { this.useBranchNameFromBuildEnvironment = useBranchNameFromBuildEnvironment; return this; } + /** + * Can be used to exclude certain properties from being emitted (e.g. filter out properties + * that you *don't* want to expose). May be useful when you want to hide + * {@code git.remote.origin.url} (maybe because it contains your repo password?), + * or the email of the committer etc. + * + * @param excludeProperties The properties that shall be excluded from generation. + * @return The {@code GitProvider} with the corresponding {@code properties exclusion list}. + */ public GitDataProvider setExcludeProperties(List excludeProperties) { this.excludeProperties = excludeProperties; return this; } + /** + * Can be used to include only certain properties into the resulting file (e.g. include only + * properties that you *want* to expose). This feature was implemented to avoid big exclude + * properties tag when we only want very few specific properties. + * The inclusion rules, will be overruled by the exclude rules (e.g. you can write an + * inclusion rule that applies for multiple properties and then exclude a subset of them). + * + * @param includeOnlyProperties The properties that shall only be included in the generation. + * @return The {@code GitProvider} with the corresponding {@code properties inclusion only list}. + */ public GitDataProvider setIncludeOnlyProperties(List includeOnlyProperties) { this.includeOnlyProperties = includeOnlyProperties; return this; } + /** + * When set to {@code true}, the plugin will not try to contact any remote repositories. + * Any operations will only use the local state of the repo. + * If set to {@code false}, it will execute {@code git fetch} operations e.g. to determine the + * {@code ahead} and {@code behind} branch information. + * + * @param offline Indicator if the plugin should operate in {@code offline} or {@code online}-mode. + * @return The {@code GitProvider} with the corresponding Indicator set. + */ public GitDataProvider setOffline(boolean offline) { this.offline = offline; return this; } + /** + * Main function that will attempt to load the desired properties from the git repository. + * + * @param evaluateOnCommit The commit that should be used as reference to generate the properties from. + * Defaults to {@code HEAD}. + * @param properties The Properties-Set that should be enriched by the generated one. + * @throws GitCommitIdExecutionException In case any problem occurred during loading of the properties from the git repository. + */ public void loadGitData(@Nonnull String evaluateOnCommit, @Nonnull Properties properties) throws GitCommitIdExecutionException { this.evaluateOnCommit = evaluateOnCommit; init(); @@ -262,6 +398,12 @@ protected void maybePut(@Nonnull Properties properties, String key, SupplierEx the type of results supplied by this supplier + */ @FunctionalInterface public interface SupplierEx { T get() throws GitCommitIdExecutionException; @@ -283,6 +425,7 @@ public static SupplierEx memoize(SupplierEx delegate) { * Regex to check for SCP-style SSH+GIT connection strings such as 'git@github.com' */ static final Pattern GIT_SCP_FORMAT = Pattern.compile("^([a-zA-Z0-9_.+-])+@(.*)|^\\[([^\\]])+\\]:(.*)|^file:/{2,3}(.*)"); + /** * If the git remote value is a URI and contains a user info component, strip the password from it if it exists. * @@ -315,7 +458,6 @@ public static SupplierEx memoize(SupplierEx delegate) { * @return returns the gitRemoteUri with stripped password (might be used in http or https) * @throws GitCommitIdExecutionException Exception when URI is invalid */ - protected String stripCredentialsFromOriginUrl(String gitRemoteString) throws GitCommitIdExecutionException { // The URL might be null if the repo hasn't set a remote diff --git a/maven/src/main/java/pl/project13/maven/git/GitCommitIdMojo.java b/maven/src/main/java/pl/project13/maven/git/GitCommitIdMojo.java index c39b740b..5a0f7f4c 100644 --- a/maven/src/main/java/pl/project13/maven/git/GitCommitIdMojo.java +++ b/maven/src/main/java/pl/project13/maven/git/GitCommitIdMojo.java @@ -338,6 +338,11 @@ public class GitCommitIdMojo extends AbstractMojo { */ @Parameter(defaultValue = "HEAD") String evaluateOnCommit; + /** + * The plugin allows to specify branch/tag/commit used when finding 'HEAD'. + * However we don't want the users to enter everything here and thus allow only the following subset. + * See https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/338 for further information + */ protected static final Pattern allowedCharactersForEvaluateOnCommit = Pattern.compile("[a-zA-Z0-9\\_\\-\\^\\/\\.]+"); /** diff --git a/maven/src/main/java/pl/project13/maven/git/GitDirLocator.java b/maven/src/main/java/pl/project13/maven/git/GitDirLocator.java index 5e671b09..22d6077e 100644 --- a/maven/src/main/java/pl/project13/maven/git/GitDirLocator.java +++ b/maven/src/main/java/pl/project13/maven/git/GitDirLocator.java @@ -26,18 +26,30 @@ import java.util.List; /** - * Encapsulates logic to locate a valid .git directory. - * + * This class encapsulates logic to locate a valid .git directory of the currently used project. + * If it's not already specified, this logic will try to find it. */ public class GitDirLocator { final MavenProject mavenProject; final List reactorProjects; + /** + * Constructor to encapsulates all references required to locate a valid .git directory + * @param mavenProject The currently used (maven) project. + * @param reactorProjects The list of reactor projects (sub-projects) of the current (maven) project. + */ public GitDirLocator(MavenProject mavenProject, List reactorProjects) { this.mavenProject = mavenProject; this.reactorProjects = reactorProjects; } + /** + * Attempts to lookup a valid .git directory of the currently used project. + * @param manuallyConfiguredDir A user has the ability to configure a git-directory with the {@code dotGitDirectory} + * configuration setting. By default it should be simply {@code ${project.basedir}/.git} + * @return A valid .git directory, or {@code null} if none could be found under the user specified location or within + * the project or it's reactor projects. + */ @Nullable public File lookupGitDirectory(@Nonnull File manuallyConfiguredDir) { if (manuallyConfiguredDir.exists()) { @@ -128,6 +140,11 @@ private File processGitDirFile(@Nonnull File file) { } } + /** + * Helper method to validate that the specified {@code File} is an existing directory. + * @param fileLocation The {@code File} that should be checked if it's actually an existing directory. + * @return {@code true} if the specified {@code File} is an existing directory, {@false} otherwise. + */ private static boolean isExistingDirectory(@Nullable File fileLocation) { return fileLocation != null && fileLocation.exists() && fileLocation.isDirectory(); } diff --git a/maven/src/main/java/pl/project13/maven/git/PropertiesReplacer.java b/maven/src/main/java/pl/project13/maven/git/PropertiesReplacer.java index d689b332..1c39f664 100644 --- a/maven/src/main/java/pl/project13/maven/git/PropertiesReplacer.java +++ b/maven/src/main/java/pl/project13/maven/git/PropertiesReplacer.java @@ -23,16 +23,27 @@ import java.util.*; import java.util.regex.Pattern; +/** + * This class encapsulates logic to perform property replacements. + * For a use-case refer to https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/317. + */ public class PropertiesReplacer { private final LoggerBridge log; private final PluginParameterExpressionEvaluator expressionEvaluator; + /** + * Constructor to encapsulates all references required to perform property replacements. + * @param log The logger to log any messages + * @param expressionEvaluator Maven's PluginParameterExpressionEvaluator + * (see https://github.com/git-commit-id/maven-git-commit-id-plugin/issues/413 why it's needed) + */ public PropertiesReplacer(LoggerBridge log, PluginParameterExpressionEvaluator expressionEvaluator) { this.log = log; this.expressionEvaluator = expressionEvaluator; } /** + * Method that performs the actual property replacement. * @param properties all properties that are being generated by the plugin * @param replacementProperties list of all replacement actions to perform */ diff --git a/maven/src/main/java/pl/project13/maven/git/ReplacementProperty.java b/maven/src/main/java/pl/project13/maven/git/ReplacementProperty.java index 6fe2bfbf..7212a9e6 100644 --- a/maven/src/main/java/pl/project13/maven/git/ReplacementProperty.java +++ b/maven/src/main/java/pl/project13/maven/git/ReplacementProperty.java @@ -23,6 +23,8 @@ import org.apache.maven.plugins.annotations.Parameter; /** + * This class represents a specific property replacement the user wants to perform. + * For a use-case refer to https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/317. * @since 2.2.3 */ public class ReplacementProperty { @@ -85,9 +87,25 @@ public class ReplacementProperty { @Parameter private List transformationRules = new ArrayList<>(); + /** + * Empty constructor + */ public ReplacementProperty() { } + /** + * Constructs a specific property replacement the user wants to perform. + * @param property The source (input) property on which the replacements should be performed (e.g. {@code git.branch}) + * @param propertyOutputSuffix The property output suffix where the replacement result should be stored in (e.g. {@code git.branch-no-slashes}) + * @param token The replacement token acts as {@code needle} that will be searched in the input property (e.g. {@code ^([^\/]*)\/([^\/]*)$}) + * @param value The value acts as the text to be written over any found tokens ("replacement"). + * @param regex If {@code true} the replacement will be performed with regular expressions or, + * if {@code false} performs a replacement with java's string.replace-function. + * @param forceValueEvaluation If {@code true} forces the plugin to evaluate the given value on *every* project. + * This might come handy if *every* project needs a unique value and a user wants to + * project specific variables like {@code project.artifactId}. + * @param transformationRules The list of transformation-rules that should be applied during replacement. + */ public ReplacementProperty(String property, String propertyOutputSuffix, String token, String value, boolean regex, boolean forceValueEvaluation, List transformationRules) { this.property = property; this.propertyOutputSuffix = propertyOutputSuffix; @@ -98,59 +116,109 @@ public ReplacementProperty(String property, String propertyOutputSuffix, String this.transformationRules = transformationRules; } + /** + * @return The source (input) property on which the replacements should be performed (e.g. {@code git.branch}) + */ public String getProperty() { return property; } + /** + * Set the source (input) property on which the replacements should be performed (e.g. {@code git.branch}) + * @param property The source (input) property + */ public void setProperty(String property) { this.property = property; } + /** + * @return The property output suffix where the replacement result should be stored in (e.g. {@code git.branch-no-slashes}) + */ public String getPropertyOutputSuffix() { return propertyOutputSuffix; } + /** + * Set the property output suffix where the replacement result should be stored in (e.g. {@code git.branch-no-slashes}) + * @param propertyOutputSuffix The property output suffix + */ public void setPropertyOutputSuffix(String propertyOutputSuffix) { this.propertyOutputSuffix = propertyOutputSuffix; } + /** + * @return The replacement token acts as {@code needle} that will be searched in the input property (e.g. {@code ^([^\/]*)\/([^\/]*)$}) + */ public String getToken() { return token; } + /** + * Set the replacement token + * @param token The replacement token + */ public void setToken(String token) { this.token = token; } + /** + * @return The value that acts as the text to be written over any found tokens ("replacement"). + */ public String getValue() { return value; } + /** + * Sets the value that acts as the text to be written over any found tokens ("replacement"). + * @param value The replacment value + */ public void setValue(String value) { this.value = value; } + /** + * @return Indicator if the replacement will be performed with regular expressions ({@code true}) or, + * if a replacement with java's string.replace-function is performed ({@code false}). + */ public boolean isRegex() { return regex; } + /** + * Sets Indicator if the replacement will be performed with regular expressions ({@code true}) or, + * if a replacement with java's string.replace-function is performed ({@code false}). + * @param regex Indicator + */ public void setRegex(boolean regex) { this.regex = regex; } - + /** + * @return Indicator if the plugin forces to evaluate the given value on *every* project ({@code true}). + */ public boolean isForceValueEvaluation() { return forceValueEvaluation; } + /** + * Sets Indicator if the plugin forces to evaluate the given value on *every* project ({@code true}). + * @param forceValueEvaluation Indicator if the plugin forces to evaluate the given value on *every* project ({@code true}). + */ public void setForceValueEvaluation(boolean forceValueEvaluation) { this.forceValueEvaluation = forceValueEvaluation; } + /** + * @return The list of transformation-rules that should be applied during replacement. + */ public List getTransformationRules() { return transformationRules; } + /** + * Sets the list of transformation-rules that should be applied during replacement. + * @param transformationRules The list of transformation-rules + */ public void setTransformationRules(List transformationRules) { this.transformationRules = transformationRules; } diff --git a/maven/src/main/java/pl/project13/maven/git/TransformationRule.java b/maven/src/main/java/pl/project13/maven/git/TransformationRule.java index af142ada..8739b49b 100644 --- a/maven/src/main/java/pl/project13/maven/git/TransformationRule.java +++ b/maven/src/main/java/pl/project13/maven/git/TransformationRule.java @@ -19,6 +19,18 @@ import org.apache.maven.plugins.annotations.Parameter; +/** + * This class represents a specific transformation logic the user wants to perform. + * + * Each {@code transformationRule} consist of + * two required fields {@code apply} and {@code action}. + * The {@code apply}-tag controls when the rule should + * be applied and can be set to {@code BEFORE} to have the rule being applied before or it can be + * set to {@code AFTER} to have the rule being applied after the replacement. + * The {@code action}-tag determines the string conversion rule that should be applied. + * + * Refer to https://github.com/ktoso/maven-git-commit-id-plugin/issues/317 for a use-case. + */ public class TransformationRule { /** * Determines when the transformation should be taken place. @@ -32,7 +44,13 @@ public class TransformationRule { private ApplyEnum applyRule; protected enum ApplyEnum { + /** + * have the rule being applied before the replacement + */ BEFORE, + /** + * have the rule being applied after the replacement + */ AFTER, ; }