Page tree
Skip to end of metadata
Go to start of metadata

Introducing Matrix Parameters

Matrix parameters key-value pairs parameters separated by a semicolon (;) that you can place anywhere on a URI.

This is a standard method for specifying parameters in HTTP (in addition to querying parameters and path parameters).

For example:

http://repo.jfrog.org/artifactory/libs-releases-local/org/libs-releases-local/org/jfrog/build-info-api/1.3.1/build-info-api-1.3.1.jar;status=DEV;rating=5

Artifactory makes use of matrix parameters for:

  1. Adding properties to artifacts as part of deployment
  2. Controlling artifact resolution using matrix parameters

Page contents

 


Dynamically Adding Properties to Artifacts on Deployment

You can add key-value matrix parameters to deploy (PUT) requests and those are automatically transformed to properties on the deployed artifact.

Since matrix parameters can be added on any part of the URL, not just at the end, you can add them to the target deployment base URL. At the time of deployment, the artifact path is added after the matrix parameters and the final deployed artifact will be assigned the defined properties.

You can even use dynamic properties, depending on our deployment framework.

When using Maven, for instance, you can add two parameters to the deployment URL: buildNumer and revision, which Maven replaces at deployment time with dynamic values from the project properties (e.g. by using the Maven build-number plugin).

So, if you define the distribution URL as:

And deploy to the qa-releases repository a jar with the following path:

Upon deployment the URL is transformed to:

And the deployed build-info-api-1.3.1.jar has two new properties:

Permissions to attach properties

You must have the 'Annotate' permission in order to add properties to deployed artifacts.


Controlling Artifact Resolution with Matrix Parameters Queries

Matrix parameters can be used to control how artifacts are found and served.

There is currently support for two types of property that can be used for resolution:

  • Non-mandatory properties
  • Mandatory properties.

Non-mandatory Properties

Non-mandatory properties are specified by a simple key=value parameter. For example "color=black"

Specifying a non-mandatory property in a query means that artifacts should be returned if at least one of the following two conditions is met:

  • There is no property with the key specified annotating the artifact
  • There is a property annotating the artifact matching both the key and value specified in the query. 

For example:

Current Artifact Property

Matrix Parameter

Resolution Result

Explanation

color=black

color=black

OK (200)

The artifact has the property with the key "color" and its value is also "black" as specified in the property query parameter

None

color=black

OK (200)

The artifact does not have a property with the key "color"
height=50

color=black

OK (200)

The artifact does not have a property with the key "color"

color=red

color=black

NOT_FOUND (404)

The artifact has the property with the key "color", but its value is not "black" so it is not returned

Mandatory Properties

Mandatory properties are specified using a plus sign together with the equals in the key-value pair: key+=value. For example "color+=black".

Specifying a mandatory property in a query means that an artifact should only be returned if at has a key-value pair exactly matching the key-value pair in the query.

For example:

Current Artifact Property

Matrix Parameter

Resolution Result

Explanation

color=black

color+=black

OK (200)

Both key and value match, so the artifact is returned

None

color+=black

NOT_FOUND (404)

The artifact does not have a property with the key "color"
height=50color+=blackNOT_FOUND (404)The artifact does not have a property with the key "color"

color=red

color+=black

NOT_FOUND (404)

The artifact has the property with the key "color", but its value is not "black" so it is not returned

Multiple properties in queries

Multiple key-value properties are combined using an AND relationship. i.e. all properties must be found on an artifact for it to be returned.


Multi-valued Properties

A matrix parameter may specify a key-value pair with multiple values separated by a comma. This means that the artifact should be returned if it contains the property with any of the specified values 

For example:

 

 

 

  • No labels