View source for Tycho/Nexus Unzip Plugin

= Nexus Unzip Repository  =

== What is it ? == 

The Unzip Repository is a plugin for the [http://www.sonatype.org/nexus/ Nexus OSS] maven repository manager.<br/>
It enables binary p2 artifact exchange between tycho projects via Nexus.

== How does it work ? == 

# The first tycho project ("producer") deploys a (zipped) p2 repository to nexus. It does this by simply using <tt>mvn deploy</tt> on a maven project with packaging type <tt>eclipse-repository</tt>
# The second tycho project ("consumer") uses the p2 repository deployed by "producer". This is done using a special "unzip" URL providing an "unzipped view" on the zipped p2 repository

== Implementation Details == 

The Unzip Repository is a new Nexus repository type that shadows the build results of a standard Maven 2 repository and allows to browse into zip and jar artifacts. 

Example: 

*p2 repo zip as artifact in Maven 2 Repository:<br>
 http&#58;//&lt;NEXUS_HOST&gt;/nexus/content/repositories/public/org/example/org.example.repository/0.1.0/org.example.repository-0.1.0-assembly.zip
*Same artifact viewed as unzipped p2 repository using a virtual unzip repo named <tt>public.unzip</tt>:
 http&#58;//&lt;NEXUS_HOST&gt;/nexus/content/repositories/'''<font color="red">public.unzip</font>'''/org/example/org.example.repository/0.1.0/org.example.repository-0.1.0-assembly.zip'''<font color="red">-unzip</font>'''

{{warning|"Unzip" URLs of redeployable artifacts (e.g. snapshots) cannot be used while the artifact is redeployed!|The current implementation does not guarantee that you find valid content under the "unzip" URL of such artifacts while they are redeployed. Take care to not access those URLs during redeployment.}}

== Installation and Configuration  ==

=== Prerequisites  ===

Nexus Unzip Repository Plugin 0.14.0 requires [http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22nexus-bundle-template%22 Nexus OSS version 2.8.x or later].

=== Download ===

Get the nexus unzip-repository-plugin version 0.14.0 from [http://repo1.maven.apache.org/maven2/org/eclipse/tycho/nexus/unzip-repository-plugin/0.14.0/unzip-repository-plugin-0.14.0-bundle.zip maven central].

=== Deploying the plug-in  ===

To enable a Nexus server to provide direct access to files inside zip/jar archives, you need to deploy the Nexus Unzip Repository Plugin to the Nexus server instance and configure a new virtual repository using the Unzip Repository type. 

#Stop the Nexus instance 
#Unzip the <tt>unzip-repository-plugin-&lt;VERSION&gt;-bundle.zip</tt> into <tt>${NEXUS_WORK}/plugin-repository/</tt>  folder 
#Restart the Nexus server 
#To verify that the Unzip Repository Plugin is activated, open the Plugin Console from the Administration sub-menu of the Nexus UI

=== Configuring an unzip repository (using hosted/proxy/virtual repo as master)  ===

WARNING: Using the Nexus Web UI you can only assign hosted, proxy and virtual repositories as the master repository. To configure a group as the used master , you need to configure it directly in the configuration file on the Nexus host machine. Details in the section below. 

#Open the Nexus Web UI 
#Login with your administrative user 
#Choose the Repositories View from the side menu 
#Open the Add menu and choose Virtual Repository. The detail view below the repository list opens a form to specify further repository configuration. 
#Enter a unique repository ID and choose a (display) name
#Choose <tt>Unzip Repository Template</tt> as the repository provider
#Select the intended repository from the list of the source nexus repositories (see below if you want to configure a group as source repository)
#Save the repository config 
#To verify the setup of the unzip repository, you can now select the repository from the repository list and start browsing the folders '''and''' into archives that you have deployed into the previously selected master repository. You can also open the URL given in the Repository Path column to browse in the standard web browser.

=== Configuring a group as master for the unzip repository  ===

All groups and repositories configuration are stored in the nexus.xml config file in the Nexus work folder. Due to a limitation of the configuration web UI, you currently have to edit this file directly in a text editor in order to configure a group repository as master. 

#Stop Nexus 
#Open <tt>${NEXUS_WORK}/conf/nexus.xml</tt> 
#Add a new repository element with following structure
 &lt;repository&gt;
   &lt;id&gt;master.group.unzip&lt;/id&gt;
   &lt;name&gt;Group Unzip&lt;/name&gt;
   &lt;providerRole&gt;org.eclipse.tycho.nexus.internal.plugin.UnzipRepository&lt;/providerRole&gt;
   &lt;providerHint&gt;org.eclipse.tycho.nexus.plugin.DefaultUnzipRepository&lt;/providerHint&gt;
   &lt;localStatus&gt;IN_SERVICE&lt;/localStatus&gt;
   &lt;notFoundCacheActive&gt;true&lt;/notFoundCacheActive&gt;
   &lt;notFoundCacheTTL&gt;15&lt;/notFoundCacheTTL&gt;
   &lt;userManaged&gt;true&lt;/userManaged&gt;
   &lt;exposed&gt;true&lt;/exposed&gt;
   &lt;browseable&gt;true&lt;/browseable&gt;
   &lt;writePolicy&gt;READ_ONLY&lt;/writePolicy&gt;
   &lt;searchable&gt;true&lt;/searchable&gt;
   &lt;localStorage&gt;
     &lt;provider&gt;file&lt;/provider&gt;
   &lt;/localStorage&gt;
   &lt;externalConfiguration&gt;
     &lt;masterRepositoryId&gt;public&lt;/masterRepositoryId&gt;
     &lt;useVirtualVersion&gt;true&lt;/useVirtualVersion&gt;
     &lt;synchronizeAtStartup&gt;false&lt;/synchronizeAtStartup&gt;
   &lt;/externalConfiguration&gt;
 &lt;/repository&gt;
Note that you specify the repository id (not the name) of the group in the <tt>masterRepositoryId</tt> element. <br>4. Restart Nexus

<span id="Virtual versions">
=== Enabling virtual versions SNAPSHOT and RELEASE  ===

Especially for <tt>SNAPSHOT</tt> versions, it's generally useful to be able to reference the latest SNAPSHOT version of a p2 repository without having to specify the actual timestamp of the latest SNAPSHOT<br>
 http&#58;//&lt;NEXUS_HOST&gt;/nexus/content/repositories/public.unzip/org/example/org.example.repository/0.1.0-SNAPSHOT/org.example.repository-0.1.0'''<font color="red">-SNAPSHOT</font>'''-assembly.zip-unzip

Again due to a limitation of the configuration web UI, you currently have to manually edit <tt>${NEXUS_WORK}/conf/nexus.xml</tt>. 
To enable virtual SNAPSHOT version expansion, configure '''useVirtualVersion=true''' in <tt>${NEXUS_WORK}/conf/nexus.xml</tt> and restart nexus. For example:
 &lt;repository&gt;
   &lt;id&gt;master.group.unzip&lt;/id&gt;
   &lt;name&gt;Group Unzip&lt;/name&gt;
   &lt;providerRole&gt;org.eclipse.tycho.nexus.internal.plugin.UnzipRepository&lt;/providerRole&gt;
   &lt;providerHint&gt;org.eclipse.tycho.nexus.plugin.DefaultUnzipRepository&lt;/providerHint&gt;
   &lt;localStatus&gt;IN_SERVICE&lt;/localStatus&gt;
   &lt;notFoundCacheActive&gt;true&lt;/notFoundCacheActive&gt;
   &lt;notFoundCacheTTL&gt;15&lt;/notFoundCacheTTL&gt;
   &lt;userManaged&gt;true&lt;/userManaged&gt;
   &lt;exposed&gt;true&lt;/exposed&gt;
   &lt;browseable&gt;true&lt;/browseable&gt;
   &lt;writePolicy&gt;READ_ONLY&lt;/writePolicy&gt;
   &lt;searchable&gt;true&lt;/searchable&gt;
   &lt;localStorage&gt;
     &lt;provider&gt;file&lt;/provider&gt;
   &lt;/localStorage&gt;
   &lt;externalConfiguration&gt;
     &lt;masterRepositoryId&gt;public&lt;/masterRepositoryId&gt;
     &lt;useVirtualVersion&gt;'''<font color="red">true</font>'''&lt;/useVirtualVersion&gt;
     &lt;synchronizeAtStartup&gt;false&lt;/synchronizeAtStartup&gt;
   &lt;/externalConfiguration&gt;
 &lt;/repository&gt;

'''<font color="red">WARNING:</font>''' the '''Anonymous user should have read permission over the virtualized repository''' otherwise when a request to an unzip URL with -SNAPSHOT is made you will get a HTTP 500 and you will see in Nexus logs an error caused by:
  org.sonatype.nexus.proxy.AccessDeniedException: Access denied on repository ID='my-hosted-snapshots', path='/path-to-the-artifact/1.0.0-SNAPSHOT/maven-metadata.xml', action='read'!

This is because when the unzipped version of a -SNAPSHOT is requested, the plugin looks for the latest timestamp making. To do this it makes an unauthenticated request to get the metadata of the this GAV on the related hosted repository.
See the [https://git.eclipse.org/c/tycho/org.eclipse.tycho.nexus.git/tree/unzip-repository-plugin/src/main/java/org/eclipse/tycho/nexus/internal/plugin/cache/SnapshotRequest.java#n51 code]
</span>

== Contributing ==

The project source code is hosted at [http://git.eclipse.org/c/tycho/org.eclipse.tycho.nexus.git/ eclipse] with the Tycho project. You can also fork it on [https://github.com/eclipse/tycho.nexus github].
See [[Tycho/Contributor Guide]] for details on how to contribute.

[[Category:Tycho|Nexus Unzip Plugin]]