jar

Documentation

Overview

Package jar implements a scanner on Java archive (jar) files.

In addition to bog standard archives, this package attempts to handle more esoteric uses, also.

Throughout the code and comments, "jar" should be understood to mean "any kind of JVM archive." A brief primer on the different kinds:

• jar: Java Archive. It's a zip with a manifest file, some compiled class files, and other assets.

• fatjar/onejar: Some jars unpacked, merged, then repacked. I gather this isn't in favor in the java scene.

• war: Webapp Archive. These are consumed by application servers like Tomcat, and are an all-in-one of code, dependencies, and metadata for configuring the server.

• ear: Enterprise Archive. These are bundles of wars, with hook points for configuration. They're only used on JEE servers, so they're comparatively rare in the real world.

Index

• Constants
• Variables
• func ValidExt(name string) bool
• type Info
  • func Parse(ctx context.Context, name string, z *zip.Reader) ([]Info, error)
  • func (i *Info) String() string
• Bugs

Constants

const MinSize = 22

MinSize is the absolute minimum size for a jar.

This is the size of an empty zip. Files smaller than this cannot be jars.

Variables

var (
	ErrUnidentified = errors.New("unidentified jar")
	ErrNotAJar      = errors.New("does not seem to be a jar")
)

These are sentinel errors that can be used with errors.Is.

var Header = []byte{'P', 'K', 0x03, 0x04}

Header is the magic bytes at the beginning of a jar.

JAR files are documented as only using the "standard" zip magic number. There are two other magic numbers (ending in "\x05\x06" and "\x07\x08" respectively) for zips, but they should not be used.

Functions

func ValidExt

func ValidExt(name string) bool

ValidExt determines if the file name extension is a valid JAR file extension.

Types

type Info

type Info struct {
	// Name is the machine name found.
	//
	// Metadata that contains a "presentation" name isn't used to populate this
	// field.
	Name string
	// Version is the version.
	Version string
	// Source is the archive member used to populate the information. If the
	// name of the archive was used, this will be ".".
	Source string
	// SHA is populated with the SHA1 of the file if this entry was discovered
	// inside another archive.
	SHA []byte
}

Info reports the discovered information for a jar file.

Any given jar may actually contain multiple jars or recombined classes.

func Parse

func Parse(ctx context.Context, name string, z *zip.Reader) ([]Info, error)

Parse returns Info structs describing all of the discovered "artifacts" in the jar.

POM properties are a preferred source of information, falling back to examining the jar manifest and then looking at the name. Anything that looks like a jar bundled into the archive is also examined.

The provided name is expected to be the full path within the layer to the jar file being provided as "z".

func (*Info) String

func (i *Info) String() string

Notes

Bugs

• Older versions of the stdlib can report io.EOF when opening malformed zips.