Maven Plugin (quokka.plugin.maven:0.1, namespace=maven)

Importing will import one or more artifacts from a Maven repository, automatically importing the runtime path, including any transitive and optional dependencies.

The import target requires that you have Maven installed as it uses a custom Maven plugin to extract the dependency information of artifacts stored in Maven repositories.

Importing also requires that a mapping is defined between the Maven id and it's quokka counterpart. There is a global set of mappings stored in the quokka repository that is downloaded automatically. This is merged will any mappings defined locally (the default location is mappings.xml in your preferences directory).

This global mappings will probably suffice if you are importing a new version of an already existing artifact. However, if you are importing something new to the repository, you will need to define your own mappings. Following is a sample mapping file:

<mappings>
    <id-mappings>
        <!-- From maven id "groupId:artifactId::classifier:version" to quokka "group:name::version" -->
        <id-mapping from="org.mortbay.jetty:jetty" to="mortbay.jetty"/>
        <id-mapping from="org.mortbay.jetty:jetty-util" to="mortbay.jetty:util"/>
        <id-mapping from="org.mortbay.jetty:jetty-plus" to="mortbay.jetty:plus"/>
        <id-mapping from="bsf:bsf" to="apache.bsf"/>
        <id-mapping from="log4j:log4j" to="apache.log4j"/>
        <id-mapping from="asm:asm" to="ow2.asm"/>
        <id-mapping from="cobertura:cobertura" to="sf.cobertura"/>
        <id-mapping from="org.apache.ant:ant-antlr" to="apache.ant:antlr"/>
        <id-mapping from="org.apache.ant:ant-apache-bcel" to="apache.ant:bcel"/>
        <id-mapping from="org.apache.ant:ant-apache-bsf" to="apache.ant:bsf"/>
    </id-mappings>
    <type-mappings>
        <!-- Mappings from maven types to quokka types. If the types match, no mapping is needed -->
        <type-mapping from="pom" to="paths"/>
    </type-mappings>
    <license-mappings>
        <!-- These are mappings between maven license names and quokka license artifacts -->
        <license-mapping from="The Apache Software License, Version 2.0" to-group="license.apache" to-version="2.0"/>
        <license-mapping from="Apache License Version 2.0" to-group="license.apache" to-version="2.0"/>
    </license-mappings>
</mappings>

Mapping notes:

• There can be many Maven ids mapped to a single quokka id. e.g. the Maven ids ant:ant and org.apache.ant:ant both map to the quokka id of apache.ant:ant
• The mappings do not have to contain the same number of tokens on each side of the mapping. e.g. cobertura:cobertura with groupId and artifactId tokens maps to the single quokka group token of sf.cobertura
• The most specific mapping wins if there are multiple possible mappings that match. When searching for a mapping, the import target looks for a match on groupId:artifactId::classifier:version then groupId:artifactId::classifier, then groupId:artifactId

If you intend to upload to the global quokka repository, make sure you've read the Upload Guide and followed the instructions, particularly regarding naming standards.

Properties:

All properties are optional unless stated otherwise.

• repository: The name of the repository to install the imported artifact into. Defaults to the project's repository.
• ids or id: Either ids or id must be specified. id is a Maven id in the format groupId:artifactId:type:classifier:version. ids refers to a file containing a list of maven ids in the same format as id. The file may contain blank lines and any line starting with # is ignored. Both properties may be specified on the command. e.g. quokka maven:import -Did=ant:ant-launcher:jar::1.6.5
• template: The maven project file that quokka uses to extract dependencies. Any occurences of @pluginVersion@ are replaced by the value of the pluginVersion property. By default, it uses an in-built template. Defaults to the latest plugin version available when the maven plugin was built.
• mvn: Path of the mvn command. Caution, you should use Maven versions >= 2.0.8 as apparently prior versions can return invalid results. Defaults to mvn.
• force: True or false. If true, the artifact will be installed even if there are inconsistencies between the paths of the imported artifact and the maven version. Defaults to false.
• localMappings: A file containing local id mappings as described above.
• remoteMappings: The location of the remote mappings file
• cache: The location where remote mappings will be cached locally until they expire
• cacheExpiry: The number of seconds until the remote mappings should be downloaded again to refresh the cache.

Although the verify target is part of the Maven plugin, it can be used for repositories that have not been imported from maven. In fact, the vast majority of verification checks performed are nothing to do with maven.

Verify is a bit like lint in that it reports not only things that are errors, but warns about things that are suspicious. If a warning turns out to be a false positive, it should be added to the verified issues file so that it is not reported again.

At present the following checks are performed:

Properties:

All properties are optional unless stated otherwise.

• repository: Mandatory. The name of the repository to verify.
• ids or id: See the import target for more information. In the case of verify however, these properties are optional and are used to limit which ids are verified.
• localVerifiedIssues: A file containing local verified issues. The verified issues file is a text file containing regular expressions of warnings to ignore. Blank lines and those starting with # are ignored. Line content after // is also ignored. The following is an example of some verified issues:

  Duplicate hashes: apache.xerces:xml-apis:jar:2.6, apache.xerces:xml-apis:jar:2.6.2
  Maven and quokka runtime paths do not match: apache\.fop:fop:jar:0\.20\.5.* // Removed mandatory dependencies on XML libs
  

• remoteVerifiedIssues: The location of the remote verified issues file
• failOnWarnings: If true (the default), warnings will result in the build failing
• compareMavenHash: If true, the hash of the artifacts will be compared to the hash in the maven repository. This is slow and is therefore disabled by default.
• compareMavenPaths: If true, the runtime path dependencies will be compared to the Maven equivalent. This is very slow (~ 3s/check) and is therefore disabled by default.
• commonRoots: Group prefixes that are irrelevant in determining if 2 artifacts are related or not. e.g. Because 2 artifacts both start with sf. doesn't mean the artifacts are related.
• template, mvn, cache & cacheExpiry, localMappings, remoteMappings: See the import target above for more information.

Plugin Paths

runtime : Runtime class path