Difference between revisions of "Equinox/p2/p2 index"

From Eclipsepedia

< Equinox‎ | p2
Jump to: navigation, search
(Example for simple repository)
 
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
p2.index
+
== What is the p2.index file?  ==
  
== What is the p2.index file? ==
+
The p2.index file provides a description of the kind of repository available at a particular location; simple or composite.
The p2.index file provides a description of the kind of repository available at a particular location.  This file is located next to the p2 metadata files (compositeContent.jar, content.jar, ...) that it describes. It is a java property file.
+
  
The presence of this file in a repository will cause p2 to replace its default lookup order for repository to match the one specified in the file. For example the example below will cause the content.xml repository to always be looked up first, and to never consult any other repository type.
+
The presence of this file in a repository will cause p2 to replace its default lookup order for repository to match the one advised in the file. This only happens the first time a repository is accessed, as p2 then caches "what worked before" and uses that on subsequent accesses. See {{bug|347448}} for more detail, links, and history behind this advisory file. The latest version of the [[Eclipse_b3/aggregator/manual| b3 aggregator]] adds an appropriate p2.index file as it publishes its p2 repository (not sure about other p2 repository publishers).  
  
version = 1
+
For example the example p2.index contents below will cause p2 to look for compositeContent.jar, and if not found, then compositeContent.xml and would skip looking for content.jar or content.xml as it normally would look for them first. (And, then, naturally, if it needed artifacts from that site, would look for compositeArtifacts.jar and if not found compositeArtifacts.xml and would skip looking for artifacts.jar and artifacts.xml). 
artifact.repository.factory.order = artifacts.xml, !
+
 
metadata.repository.factory.order = content.xml, !
+
  version = 1
 +
  metadata.repository.factory.order = compositeContent.xml,\!
 +
  artifact.repository.factory.order = compositeArtifacts.xml,\!
  
 
== How does it help me? ==
 
== How does it help me? ==
Line 14: Line 15:
  
 
== What happens if I get it wrong ? ==
 
== What happens if I get it wrong ? ==
Should you get the content of this file wrong, the repository will fail loading. For example specifying compositeContent.xml where the repository is a content.xml will cause p2 to only look for compositeContent.xml and never look at the content.xml.  
+
Should you get the content of this file wrong, the repository will fail loading. For example specifying compositeContent.xml where the repository is a content.xml will cause p2 to only look for compositeContent.xml and never look for the content.xml.
 +
 
 +
== How many files for composite repositories? ==
 +
Given that a composite repository is just a repository that refers to other repositories, the full benefit of p2.index can only be achieved if every child repo has the file (with only a few exceptions to this general rule) the but benefit is greatest, or most important, for composite sites as that is where the "default rules" are changed the most.
 +
 
 +
== Why say 'xml' instead of 'jar' in factory name? ==
 +
 
 +
The content of p2.index does not reflect whether the files are zipped or not.
 +
 
 +
To quote the output of the b3 aggregator:
 +
 
 +
:Please note that the values in this file denotes repository factories and
 +
:not files. The factory '<name>.xml' will look for both the <name>.jar
 +
:and the <name>.xml file, in that order
 +
 
 +
For example for a simple repository that contains artifacts.jar and content.jar, the p2.index would still name: "artifacts.xml" and "content.xml" as the factories.
 +
 
 +
As an aside, jarred versions of p2 content and artifacts files should always be provided for production sites, when the files are of any substantial size.
 +
 
 +
==Examples==
 +
 
 +
Note, your p2.index file should contain the minimum data possible (that is, no comments) since even though it is small, it currently is requested hundreds of thousands of times on enterprise systems and currently is not cached (See {{bug|310546}}).
 +
 
 +
=== Example for composite repository ===
 +
 
 +
 
 +
Use this content in your p2.index file, if your repository location contains compositeContent.jar/xml and compositeArtifacts.jar/xml.
 +
 
 +
  version = 1
 +
  metadata.repository.factory.order = compositeContent.xml,\!
 +
  artifact.repository.factory.order = compositeArtifacts.xml,\!
 +
 
 +
=== Example for simple repository ===
 +
 
 +
Use this content in your p2.index file, if your repository location contains content.jar/xml and artifacts.jar/xml.  
  
== How many files for composite repositories ==
+
  version = 1
Given that a composite repository is just a repository that refers to other repositories, the full benefit of p2.index can only be achieved if every child repo has the file.
+
  metadata.repository.factory.order = content.xml,\!
 +
  artifact.repository.factory.order = artifacts.xml,\!
 +
 
 +
=== Example for a mixed repository ===
  
== Jar vs XML extension ==
+
Use this content in your p2.index file, if your repository location contains a content.jar but a compositeArtifacts.jar.
  
== Example for composite repository ==
+
This case should be rare, but does happen to be used at part of our main Simultaneous Release repositories
  
== Example for simple repository ==
+
  version = 1
version = 1
+
  metadata.repository.factory.order=content.xml,\!
artifact.repository.factory.order = artifacts.xml, !
+
  artifact.repository.factory.order=compositeArtifacts.xml,\!
metadata.repository.factory.order = content.xml, !
+
  
  
 
[[Category:Equinox_p2]]
 
[[Category:Equinox_p2]]

Latest revision as of 13:32, 2 March 2012

Contents

[edit] What is the p2.index file?

The p2.index file provides a description of the kind of repository available at a particular location; simple or composite.

The presence of this file in a repository will cause p2 to replace its default lookup order for repository to match the one advised in the file. This only happens the first time a repository is accessed, as p2 then caches "what worked before" and uses that on subsequent accesses. See bug 347448 for more detail, links, and history behind this advisory file. The latest version of the b3 aggregator adds an appropriate p2.index file as it publishes its p2 repository (not sure about other p2 repository publishers).

For example the example p2.index contents below will cause p2 to look for compositeContent.jar, and if not found, then compositeContent.xml and would skip looking for content.jar or content.xml as it normally would look for them first. (And, then, naturally, if it needed artifacts from that site, would look for compositeArtifacts.jar and if not found compositeArtifacts.xml and would skip looking for artifacts.jar and artifacts.xml).

 version = 1
 metadata.repository.factory.order = compositeContent.xml,\!
 artifact.repository.factory.order = compositeArtifacts.xml,\!

[edit] How does it help me?

As a provider of a repository, it does not help you directly, but it helps your users to get a better experience and also slightly reduce the number of hits your server will be subject to.

[edit] What happens if I get it wrong ?

Should you get the content of this file wrong, the repository will fail loading. For example specifying compositeContent.xml where the repository is a content.xml will cause p2 to only look for compositeContent.xml and never look for the content.xml.

[edit] How many files for composite repositories?

Given that a composite repository is just a repository that refers to other repositories, the full benefit of p2.index can only be achieved if every child repo has the file (with only a few exceptions to this general rule) the but benefit is greatest, or most important, for composite sites as that is where the "default rules" are changed the most.

[edit] Why say 'xml' instead of 'jar' in factory name?

The content of p2.index does not reflect whether the files are zipped or not.

To quote the output of the b3 aggregator:

Please note that the values in this file denotes repository factories and
not files. The factory '<name>.xml' will look for both the <name>.jar
and the <name>.xml file, in that order

For example for a simple repository that contains artifacts.jar and content.jar, the p2.index would still name: "artifacts.xml" and "content.xml" as the factories.

As an aside, jarred versions of p2 content and artifacts files should always be provided for production sites, when the files are of any substantial size.

[edit] Examples

Note, your p2.index file should contain the minimum data possible (that is, no comments) since even though it is small, it currently is requested hundreds of thousands of times on enterprise systems and currently is not cached (See bug 310546).

[edit] Example for composite repository

Use this content in your p2.index file, if your repository location contains compositeContent.jar/xml and compositeArtifacts.jar/xml.

 version = 1
 metadata.repository.factory.order = compositeContent.xml,\!
 artifact.repository.factory.order = compositeArtifacts.xml,\!

[edit] Example for simple repository

Use this content in your p2.index file, if your repository location contains content.jar/xml and artifacts.jar/xml.

 version = 1
 metadata.repository.factory.order = content.xml,\!
 artifact.repository.factory.order = artifacts.xml,\!
 

[edit] Example for a mixed repository

Use this content in your p2.index file, if your repository location contains a content.jar but a compositeArtifacts.jar.

This case should be rare, but does happen to be used at part of our main Simultaneous Release repositories

 version = 1
 metadata.repository.factory.order=content.xml,\!
 artifact.repository.factory.order=compositeArtifacts.xml,\!