docs/src/docbkx/appendix/appendix-osgi-repo.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<appendix id="appendix-osgi-repo">
    <title>Gemini Blueprint OSGi Repository</title>

    <para>At the moment, most libraries are not released as OSGi bundles which means they cannot be used inside the OSGi space unless they
    are embedded in other bundles. Though there are <ulink url="http://www.aqute.biz/Code/Bnd">tools</ulink> that make the bundling 
    process easy, it is desirable to have the artifacts prepacked so they can be used immediately for development.</para> 
    
    <para>SpringSource <ulink url="http://www.springsource.com/repository/">Enterprise Bundle Repository</ulink> (or SpringSource Repository) addresses this problem by 
    providing 
    <quote>a collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework</quote> (taken
    from the Repository <ulink url="http://www.springsource.com/repository/app/faq">FAQ</ulink>). With the availability of the Bundle Repository,
    the Gemini Blueprint old repository (see below) has been deprecated and it is being used until migrating completely to SpringSource Repository. It is highly recommended
    that users migrate as well to SpringSource Repository as it provides significantly more libraries and it is intended to be a user-facing infrastructure component. 
    </para>
    
    <section id="appendix-osgi-repo:old-repo">
    	<title>Gemini Blueprint Temporary OSGi Repository</title>
    	
    	<para>Unfortunately, not all Gemini Blueprint dependencies are available in SpringSource Repository and thus Gemini Blueprint still needs to maintain some of its own 
    	dedicated Maven <ulink url="http://maven.apache.org/guides/introduction/introduction-to-repositories.html">repository</ulink> available
	    at <literal>http://maven.springframework.org/osgi</literal>.
	    
	    <warning>The repository is <emphasis>provided as-is</emphasis> without any kind of support. The repository structure/content
	    can (and will) change until it becomes stable. Before using Gemini Blueprint repository make sure the needed artifact are not available
	    in SpringSource Repository. These being said, we hope you find it useful and we'd like to <ulink url="http://jira.springframework.org/browse/OSGI">know</ulink> 
	    if there are improvement that can be made to it.</warning> 
	    </para>

	<section id="appendix-osgi-repo:conventions">
		<title>Repository Conventions</title>
		
		<para>Currently, all the artifacts published in the repository are marked as <literal>SNAPSHOT</literal>s meaning that, in time, their
		content can change. This allows clients to download possible manifest updates made to the libraries. We foresee that, as the library usage
		increases, several popular items will have the <literal>SNAPSHOT</literal> marker remove.
		Additionally, to differentiate the <emphasis>OSGi</emphasis>-enabled artifacts from the original ones, all libraries are placed under
		<literal>org.eclipse.gemini.blueprint</literal> group and their names contains a <literal>.osgi</literal> suffix.</para>
		
		<para>So for example, an OSGi version of <literal>mx4j-3.0.2</literal> jar is available in the Gemini Blueprint OSGi repository under at:
		<literal>org.eclipse.gemini.blueprint/mx4j.osgi/3.0.2-SNAPSHOT/mx4j.osgi-3.0.2-SNAPSHOT.jar</literal></para>
	</section>
	
	<section id="appendix-osgi-repo:browsing">
		<title>Browsing The Repository Content</title>
		
		<para>The repository is currently hosted at Amazon <ulink url="http://aws.amazon.com/s3">S3</ulink>. To browse the repository structure,
		use a S3 compatible browser (such as <ulink url="http://s3browse.com/explore/maven.springframework.org/osgi/org.eclipse.gemini.blueprint/">this</ulink> one)
		since a vanilla web browse will not be suitable. 
		</para>
	</section>
	
	<section id="appendix-osgi-repo:maven">
		<title>Using The Repository With Maven</title>
		
		<para>The use the repository, simply add it ot the <literal>repositories</literal> group; since the repository 
		contains <literal>SNAPSHOT</literal> artifacts, make sure to mark it accordingly:</para>
		
		<programlisting language="xml"><![CDATA[<repositories>
  <repository>
    <id>spring-osgified-artifacts</id>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
    <name>Springframework Maven OSGified Artifacts Repository</name>
    <url>http://maven.springframework.org/osgi</url>
  </repository>
</repositories>]]></programlisting>
		
	</section>

	<section id="appendix-osgi-repo:ant">
		<title>Using The Repository With Ant/Ivy</title>
		
		<para>When using <ulink url="http://ant.apache.org/">Ant</ulink> consider using the excellent <ulink url="http://ant.apache.org/ivy/">Ivy</ulink>
		subproject for retrieving the OSGi dependencies from the Gemini Blueprint repository as Ivy can work with a Maven-style repository. Please see the 
		Ivy <ulink url="http://ant.apache.org/ivy/history/latest-milestone/tutorial/start.html">tutorial</ulink> for more information.</para>
	</section>
	
	</section>
</appendix>