org.azyva.dragom.maven

Class Pom

java.lang.Object

org.azyva.dragom.maven.Pom

public class Pom
extends Object

This class allows reading and modifying the data in a POM file that are pertinent for Dragom, namely the version information and referenced artifacts versions (parent, dependencies and dependencyManagement elements). It is not meant to be a general purpose API for editing POM files. It works directly at the POM level. It does not attempt to infer an effective POM. This class does its best to preserve the original POM file, modifying only what needs to be modified. But given that it uses the DOM API provided in the JDK, its has the following limitations in this regard: - Attribute order is not preserved; - Whitespace between attribute declarations is not preserved; - Formatting in any XML comment appearing before th root element is not preserved. It is believed that these limitations will not cause major problems. Generally using the DOM API (Transformer), any non-comment elements before the root element of and anything after the close of the root element is not preserved either. However this class does preserve bytes before and after the root element or the first comment element with special code. This includes the XML and DOCTYPE declarations, if any. A solution would be to use another parser such as VTD-XML. But such a parser is not usable transparently through the JDK XML parser API. This class manages the following references within the POM file: - Parent - DependencyManagement - Dependencies References could exists elsewhere by using more advanced Maven features. These are not supported. Referenced versions are not interpreted in any way. If a version reference uses a property expression such as ${project.version}, the expression itself is returned. Artifact versions are returned as simple String. During the design of this class we considered to use the class ArtifactVersion. But we figured this was at a higher level than this class. This class also allows listing submodules.

Author:

David Raymond

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Pom.ReferencedArtifact Holds information about a referenced artifact.
static class	Pom.ReferencedArtifactType Enumeration of the different types of referenced artifacts managed by this class.

Constructor Summary

Constructors

Constructor and Description
Pom() Constructor.

Method Summary

Modifier and Type	Method and Description
String	getArtifactId()
String	getGroupId()
List<Pom.ReferencedArtifact>	getListReferencedArtifact(EnumSet<Pom.ReferencedArtifactType> enumSetReferencedArtifactType, String filterGroupId, String filterArtifactId, String filterVersion) Gets referenced artifacts.
List<String>	getListSubmodule() Gets the list of submodules.
Pom.ReferencedArtifact	getParentReferencedArtifact() Gets the parent referenced artifact.
String	getResolvedGroupId()
String	getResolvedVersion()
String	getSimpleElement(String elementPath) Gets a simple element in the POM.
String	getVersion()
void	loadPom() Loads the POM file identified by the pathPom property.
static void	main(String[] args)
void	savePom() Saves the loaded POM into the file identified by the pathPom property.
void	setPathPom(Path pathPom)
void	setReferencedArtifactVersion(Pom.ReferencedArtifact referencedArtifact, String version) Modifies the version of a referenced artifact.
void	setVersion(String version) Sets the version of the artifact.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Pom

public Pom()

Constructor.

Method Detail

setPathPom

public void setPathPom(Path pathPom)

Parameters:

pathPom - Path to the POM.

loadPom

public void loadPom()

Loads the POM file identified by the pathPom property.

savePom

public void savePom()

Saves the loaded POM into the file identified by the pathPom property.

getGroupId

public String getGroupId()

Returns:

GroupId of the artifact. Can be null if the POM does not specify the groupId (if it inherits it from its parent).

getResolvedGroupId

public String getResolvedGroupId()

Returns:

GroupId of the artifact either from the groupId element or that of the parent if not provided. null can be returned if no groupId can be resolved (which is an error).

getArtifactId

public String getArtifactId()

Returns:

ArtifactId of the artifact. Can be null if the POM does not specify an artifactId (which is an error).

getVersion

public String getVersion()

Returns:

Version of the artifact. Can be null if the POM does not specify the artifact version (if it inherits it from its parent).

setVersion

public void setVersion(String version)

Sets the version of the artifact. The version of the artifact must already be specified within the POM. It is not allowed to set the artifact version for a POM that does not already set it.

Parameters:

version - See description.

getResolvedVersion

public String getResolvedVersion()

Returns:

Version of the artifact either from the version element or that of the parent if not provided. null can be returned if no version can be resolved (which is an error).

getSimpleElement

public String getSimpleElement(String elementPath)

Gets a simple element in the POM. This method factors the common part of other get methods in this class.

Parameters:

elementPath - Path of the element within the POM.

Returns:

See description. Can be null if the POM does not specify the element.

getListReferencedArtifact

public List<Pom.ReferencedArtifact> getListReferencedArtifact(EnumSet<Pom.ReferencedArtifactType> enumSetReferencedArtifactType,
                                                              String filterGroupId,
                                                              String filterArtifactId,
                                                              String filterVersion)

Gets referenced artifacts. Only complete references are returned. If a dependency does not include the version (because it is specified in a dependencyManagement element of some parent, it is not returned because it is of no interest to the Dragom.

Parameters:

enumSetReferencedArtifactType - EnumSet of the types of referenced artifact to return. For example, if only the parent is needed, specify EnumSet.of(ReferencedArtifactType.PARENT). If all types of referenced artifacts are needed, specify EnumSet.allOf(ReferencedArtifactType.class).

filterGroupId - Restrict retrieved referenced artifacts to those matching this groupId. If null, no filtering is applied on the groupId.

filterArtifactId - Restrict retrieved referenced artifacts to those matching this artifactId. If null, no filtering is applied on the artifactId.

filterVersion - Restrict retrieved referenced artifacts to those matching this version. If null, no filtering is applied on the version.

Returns:

List of ReferencedArtifact.

getParentReferencedArtifact

public Pom.ReferencedArtifact getParentReferencedArtifact()

Gets the parent referenced artifact. This infomration can be obtained using getListReferencedArtifact, but since there can be only one parent, a dedicated method is provided that is easier to to use.

Returns:

Parent ReferencedArtifact.

setReferencedArtifactVersion

public void setReferencedArtifactVersion(Pom.ReferencedArtifact referencedArtifact,
                                         String version)

Modifies the version of a referenced artifact. Note that following such a modification, referencedArtifact becomes effectively invalid since the version has been modified and it does not match any referenced artifact anymore.

Parameters:

referencedArtifact - Referenced artifact. Must generally have been returned by getListReferencedArtifact. There must be a matching referenced artifact in the POM.

version - New version.

getListSubmodule

public List<String> getListSubmodule()

Gets the list of submodules. The submodules are identified as in the POM, meaning that they actually are relative directory paths from the directory of the POM. Presumably the POM has the packaging type "pom", but this is not enforced.

Returns:

See description.

main

public static void main(String[] args)