Ruby Mojos are annotated using comments in Ruby source files. A
single annotation like @parameter takes a number
of attributes, and each of these attributes must be specified on the
same line. There can be no line-breaks between an annotations attribute
in the Ruby source. Both classes and parameters are annotated.
Parameters are annotated with four annotations:
@parameter, @required,
@readonly, and
@deprecated. The
@parameter attribute takes the following
attributes:
- alias
-
An alias for the parameter. An alternate name which can be used to populate the same parameter.
- default-value
-
Provides a default value to the parameter if the supplied value or the parameter expression produces a null result. In
echo.rb, we specify the default as "Hello Maven World". - expression
-
Contains an expression which can resolve to a Maven property or a System property.
- type
-
The fully qualified Java type of the parameter. If the type is not specified it will default to
java.lang.String.
In addition to the @parameter annotation, a
parameter can take the following annotations:
- @required "<true|false>"
-
Marks the parameter as being required. The default value is false.
- @readonly "<true|false>"
-
Marks the parameter as read-only. If this is true, you may not override the default value or the value from the expression from the command line. The default value is false.
- @deprecated "<true|false>"
-
Marks the parameter as deprecated. The default value is false.
Putting this altogether, a fully annotated message parameter from
echo.rb would look like the following code:
# @parameter type="java.lang.String" default-value="Hello Maven World" expression="${message}"
# @readonly true
# @required false
# @deprecated false
def message
end
Ruby Mojo classes are annotated with the following attributes:
- @goal
-
Specifies the name of the goal.
- @phase
-
The default phase to bind this goal to.
- @requiresDependencyResolution
-
True if the Mojo requires that dependencies be resolved before execution.
- @aggregator
-
Marks this mojo as an aggregator.
- @execute
-
Provides the opportunity to execute a goal or lifecycle phase before executing this Mojo. The @execute annotation takes the following attributes:
- goal
-
Name of the goal to execute
- phase
-
Name of the lifecycle phase to execute
- lifecycle
-
Name of the lifecycle (if other than default)
For an example of an annotated Mojo class, consider the following code example:
# Completes some build task # @goal custom-goal # @phase install # @requiresDependencyResolution false # @execute phase=compile class CustomMojo < Mojo ... end
Mojo parameters can reference Java classes and Maven properties. The following example shows you how to get access to the Maven Project object from a Ruby Mojo.
Example 18.6. Referencing a Maven Project from a Ruby Mojo
# This is a mojo description
# @goal test
# @phase validate
class Test < Mojo
# @parameter type="java.lang.String" default-value="nothing" alias="a_string"
def prop
end
# @parameter type="org.apache.maven.project.MavenProject" expression="${project}"
# @required true
def project
end
def execute
info "The following String was passed to prop: '#{$prop}'"
info "My project artifact is: #{$project.artifactId}"
end
end
run_mojo Test
In the previous example, we can access properties on the
Project class using standard Ruby syntax. If
you put test.rb in
firstruby-maven-plugin's
src/main/scripts directory, install the plugin,
and then run it, you will see the following output:
$ mvn install ... [INFO] [plugin:descriptor] [INFO] Using 3 extractors. [INFO] Applying extractor for language: java ... [INFO] Applying extractor for language: jruby [INFO] Ruby Mojo File: /echo.rb [INFO] Ruby Mojo File: /test.rb [INFO] Extractor for language: jruby found 2 mojo descriptors. ... $ mvn firstruby:test ... [INFO] [firstruby:test] [INFO] The following String was passed to prop: 'nothing' [INFO] My project artifact is: firstruby-maven-plugin
