maven

Documentation

Overview

Package maven provides an HTTP client for Maven Central.

Overview

This package fetches artifact metadata from Maven Central (https://search.maven.org), the primary repository for Java packages.

Usage

client, err := maven.NewClient(24 * time.Hour)
if err != nil {
    log.Fatal(err)
}

artifact, err := client.FetchArtifact(ctx, "com.google.guava:guava", false)
if err != nil {
    log.Fatal(err)
}

fmt.Println(artifact.Coordinate())
fmt.Println("Dependencies:", artifact.Dependencies)

Coordinates

Maven artifacts are identified by coordinates in the format "groupId:artifactId". For example: "com.google.guava:guava", "org.apache.commons:commons-lang3".

ArtifactInfo

[FetchArtifact] returns an ArtifactInfo containing:

• GroupID, ArtifactID: Artifact identity
• Version: Latest version from Maven Central search
• Dependencies: Compile-scope dependencies from POM
• Description: Project description from POM
• URL: Project homepage/repository URL from POM (e.g., GitHub URL)

Caching

Responses are cached to reduce load on Maven Central. The cache TTL is set when creating the client. Pass refresh=true to bypass the cache.

Dependency Filtering

Only compile-scope dependencies are included. Test, provided, and optional dependencies are filtered out. Dependencies with unresolved Maven properties (${...}) are skipped.

Two-Phase Fetch

The client performs two requests:

1. Maven Central Search API to find the latest version
2. Direct POM fetch from repo1.maven.org for dependencies

Index

• type ArtifactInfo
  • func (a *ArtifactInfo) Coordinate() string
• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchArtifact(ctx context.Context, coordinate string, refresh bool) (*ArtifactInfo, error)
  • func (c *Client) FetchArtifactVersion(ctx context.Context, coordinate, version string, refresh bool) (*ArtifactInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, coordinate string, refresh bool) ([]string, error)
• type Dependency

Types

type ArtifactInfo

type ArtifactInfo struct {
	GroupID      string       // Maven groupId (e.g., "com.google.guava", never empty in valid info)
	ArtifactID   string       // Maven artifactId (e.g., "guava", never empty in valid info)
	Version      string       // Latest version (e.g., "32.1.3-jre", never empty in valid info)
	Dependencies []Dependency // Compile-scope dependencies with versions (nil or empty if none or POM fetch failed)
	Description  string       // Artifact description from POM (may be empty)
	Repository   string       // Source code repository URL from POM SCM section (may be empty)
	HomePage     string       // Project homepage URL from POM (may be empty, often same as Repository)
	License      string       // License name from POM (may be empty)
	LicenseURL   string       // License URL from POM (may be empty)
}

ArtifactInfo holds metadata for a Java artifact from Maven Central.

Artifacts are identified by "groupId:artifactId" coordinates. Dependencies include only compile-scope dependencies; test, provided, and optional deps are excluded. Dependencies with unresolved Maven properties (${...}) are skipped.

Zero values: All string fields are empty, Dependencies is nil. This struct is safe for concurrent reads after construction.

func (*ArtifactInfo) Coordinate

func (a *ArtifactInfo) Coordinate() string

Coordinate returns the Maven coordinate string "groupId:artifactId". Example: "com.google.guava:guava"

type Client

type Client struct {
	*integrations.Client
	// contains filtered or unexported fields
}

Client provides access to the Maven Central repository API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client

NewClient creates a Maven Central client with the given cache backend.

Parameters:

• backend: Cache backend for HTTP response caching (use storage.NullBackend{} for no caching)
• cacheTTL: How long responses are cached (typical: 1-24 hours)

The returned Client is safe for concurrent use.

func (*Client) FetchArtifact

func (c *Client) FetchArtifact(ctx context.Context, coordinate string, refresh bool) (*ArtifactInfo, error)

FetchArtifact retrieves metadata for a Java artifact from Maven Central (latest version).

The coordinate parameter must be in the format "groupId:artifactId". Examples: "com.google.guava:guava", "org.apache.commons:commons-lang3" Coordinate cannot be empty or missing the colon separator.

If refresh is true, the cache is bypassed and a fresh API call is made. If refresh is false, cached data is returned if available and not expired.

This method performs two API calls:

1. Maven Central Search API to find the latest version
2. Direct POM fetch to extract dependencies

POM fetch failures are silently ignored; Dependencies will be empty/nil if it fails.

Returns:

• ArtifactInfo populated with metadata on success
• integrations.ErrNotFound if the artifact doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)
• Error if coordinate format is invalid
• Other errors for JSON decoding failures

The returned ArtifactInfo pointer is never nil if err is nil. This method is safe for concurrent use.

func (*Client) FetchArtifactVersion

func (c *Client) FetchArtifactVersion(ctx context.Context, coordinate, version string, refresh bool) (*ArtifactInfo, error)

FetchArtifactVersion retrieves metadata for a specific version of a Java artifact.

The coordinate parameter must be in the format "groupId:artifactId". The version must be an exact version string (e.g., "32.1.3-jre").

If refresh is true, the cache is bypassed and a fresh API call is made.

Returns:

• ArtifactInfo populated with metadata on success
• integrations.ErrNotFound if the artifact or version doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)

This method is safe for concurrent use.

func (*Client) ListVersions

func (c *Client) ListVersions(ctx context.Context, coordinate string, refresh bool) ([]string, error)

ListVersions returns all available versions for an artifact, sorted from oldest to newest.

type Dependency

type Dependency struct {
	Name       string // Maven coordinate (groupId:artifactId)
	Constraint string // Version from POM (may contain Maven properties or ranges)
}

Dependency represents a Maven dependency with version information.