Skip to content
Browse files

Updated base class names and README

  • Loading branch information...
1 parent 3bd9391 commit 069c9cdc2cf9d5e890c2b80b67dc1cf4cf80fdf8 @njbartlett njbartlett committed Aug 23, 2012
View
118 README.md
@@ -1,113 +1,46 @@
Introduction
============
-BIndex2 program is a small Java program that generates repository indexes compliant with the Repository Service Specification version 1.0, as defined in the OSGi Service Platform Service Compendium, Release 5. It can recurse over a directory structure generates a repository.xml file. The URLs can be rewritten using a template.
+RepoIndex program is a small Java program that generates repository indexes compliant with the Repository Service Specification version 1.0, as defined in the OSGi Service Platform Service Compendium, Release 5. It can recurse over a directory structure generates a repository.xml file. The URLs can be rewritten using a template.
-BIndex2 is a command line application that can easily be integrated in scripts. It is also an OSGi bundle that publishes a service under the `ResourceIndexer` interface, and a standalone library that can be used in conventional Java runtimes. While mainly intended for indexing OSGi bundles, it can generate metadata for any arbitrary file type by extending it with pluggable `ResourceAnalyzer` objects.
+RepoIndex is a command line application that can easily be integrated in scripts. It is also an OSGi bundle that publishes a service under the `ResourceIndexer` interface, and a standalone library that can be used in conventional Java runtimes. While primarily intended for indexing OSGi bundles, it can generate metadata for any arbitrary file type by extending it with pluggable `ResourceAnalyzer` objects.
Files
=====
-BIndex2 is shipped as two alternative forms:
+RepoIndex is shipped as two alternative forms:
-* `bindex2.lib` is a pure library and OSGi bundle. Use this if you want to embed index generation functionality into an existing application. See sections "Library Usage" and "OSGi Bundle Usage" below.
+* `org.osgi.impl.bundle.repoindex.lib` is a pure library and OSGi bundle. Use this if you want to embed index generation functionality into an existing application. See sections "Library Usage" and "OSGi Bundle Usage" below.
-* `bindex2.cli` is a standalone command-line application. See section "Command Line Usage" below.
+* `org.osgi.impl.bundle.repoindex.cli` is a standalone command-line application. See section "Command Line Usage" below.
-* `bindex2.ant` (not available yet) is an ANT task. See section "ANT Usage" below.
+**N.B.:** Choose either lib OR cli, you do not need both.
Command Line Usage
==================
The basic command line usage is as follows:
- java -jar bindex2.cli.jar -n Bundles bundles/*.jar
+ java -jar org.osgi.impl.bundle.repoindex.cli.jar bundles/*.jar
-This generates an index file in the local directory named `repository.xml` with metadata for all JAR files found under the `bundles` directory. The repository name will be set to `Bundles` and the URLs for the resources will be relative to the current directory, i.e.:
+This generates an index file in the local directory named `index.xml.gz` with metadata for all JAR files found under the `bundles` directory. The content URLs for the resources will be relative to the current directory, i.e.:
<attribute name='osgi.content' value='bundles/foo.jar'/>
-The full set of options is as follows:
-
- java -jar bindex2.cli.jar
- [-h]
- [-r repository.(xml|zip)]
- [-n Untitled]
- [-d rootdir]
- [-l file:license.html]
- [-v]
- [-stylesheet http://www.osgi.org/www/obr2html.xsl]
- [-t "%s" symbolic name "%v" version "%f" filename "%p" dirpath ]
- <file> [<file>*]
-
-<table>
- <tr>
- <th>Option</th>
- <th>Description</th>
- </tr>
-
- <tr>
- <td>`-h`</td>
- <td>Provide short description of command line options.</td>
- </tr>
-
- <tr>
- <td>`-r repository.xml`</td>
- <td>Set the name of the repository file as it is stored in the on the file system. The default is repository.xml. The extension may also be .zip. In that case a zip file is created with a single entry called repository.xml.</td>
- </tr>
-
- <tr>
- <td>`-n Untitled`</td>
- <td>Sets the name of the repository as declared in the `name` attribute on the top-level `repository` element of the XML index document.</td>
- </tr>
-
- <tr>
- <td>`d rootdir`</td>
- <td>Sets the root directory from where files are indexed. Default is the current directory.</td>
- </tr>
-
- <tr>
- <td>`-l licence.html`</td>
- <td>Provides a default for the license file. If the bundle itself does not provide a license file, this license is used. There is no default provided.</td>
- </tr>
-
- <tr>
- <td>`-v`</td>
- <td>Enables verbose reporting to the console.</td>
- </tr>
-
- <tr>
- <td>`-stylesheet <stylesheet>`</td>
- <td>Sets a custom stylesheet for the xml. The default style sheet is `http://www.osgi.org/www/obr2html.xsl`.</td>
- </tr>
-
- <tr>
- <td>`-t <template>`</td>
- <td>
- <p>Use a template to make the URL of the resource. The template supports the following keys. The examples assume d1/d2/f1.jar with com.acme.bundle as symbolic name and 1.0 as version:</p>
-
- <pre>
- %s com.acme.bundle Bundle Symbolic Name
- %v 1.0 Bundle Version
- %p d1/d2 Relative directory path of current working directory
- %f f1.jar File name of resource
- </pre>
- </td>
- </tr>
-</table>
+The full set of command line options can be obtained by executing with the `-h` option.
If custom resource analyzers are required (see below), these can be simply placed on the Java runtime classpath. In this case the `java -jar` launch method cannot be used, so it is necessary to launch with the application class name as follows:
- java -cp bindex2.jar;foo-analyzer.jar \
+ java -cp org.osgi.impl.bundle.repoindex.cli.jar;MyAnalyzer.jar \
org.osgi.impl.bundle.bindex.cli.Index \
- -n MyRepo bundles/*.jar
+ bundles/*.jar
Library Usage
=============
-BIndex2 can be used as a JAR library in a conventional Java application or web/Java EE container by adding `bindex2.lib.jar` to your application classpath. The API is as follows:
+RepoIndex can be used as a JAR library in a conventional Java application or web/JavaEE container by adding `org.osgi.impl.bundle.repoindex.lib.jar` to your application classpath. The API is as follows:
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
// optional: add one or more custom resource analyzers
indexer.add(new MyExtenderResourceAnalyzer(), null);
@@ -116,10 +49,10 @@ BIndex2 can be used as a JAR library in a conventional Java application or web/J
config.put(ResourceIndexer.REPOSITORY_NAME, "My Repository");
Set<File> inputs = findInputs();
- Writer output = new FileWriter("repository.xml");
+ OutputStream output = new FileOutputStream("index.xml.gz");
indexer.index(inputs, output, config);
-Note that it is not generally encouraged to instantiate the `BIndex2` class directly as shown, since this creates an implementation dependency. It is better to use the `ResourceIndexer` API interface along with a Dependency Injection framework such as Guice or Spring to supply the instance. It is even better to use `ResourceIndexer` as an OSGi Service as shown in the next section.
+Note that it is not generally encouraged for client code to directly instantiate `RepoIndex` as shown, since this creates an implementation dependency. It is better to use the `ResourceIndexer` API interface along with a Dependency Injection framework such as Guice or Spring to supply the instance. Even better, use `ResourceIndexer` as an OSGi Service as shown in the next section.
Resource analyzers are added with an optional Filter, which is matched against incoming resources as they are processed. If the filter is `null` then the analyzer is invoked for all incoming resources. Filters are generated using the `org.osgi.framework.FrameworkUtil.createFilter()` method, for example:
@@ -133,7 +66,7 @@ For more information on the filter string syntax and the properties available to
OSGi Bundle Usage
=================
-`bindex2.lib` is also an OSGi bundle that publishes a service under the interface `org.osgi.service.bindex.ResourceIndexer` when in ACTIVE state. For example, to use the `ResourceIndexer` service from a Declarative Services component:
+`org.osgi.impl.bundle.repoindex.lib` is also an OSGi bundle that publishes a service under the interface `org.osgi.service.indexer.ResourceIndexer` when in ACTIVE state. For example, to use the `ResourceIndexer` service from a Declarative Services component:
@Reference
public void setIndexer(ResourceIndexer indexer) {
@@ -145,7 +78,7 @@ OSGi Bundle Usage
indexer.index(input, output, config);
}
-When used as an OSGi bundle, BIndex2 uses the "Whiteboard Pattern" to find custom resource analyzers. The filter, if required, can be given as a property of the service. For example to register an analyzer for WAR files, again using Declarative Services annotations:
+When used as an OSGi bundle, RepoIndex uses the "Whiteboard Pattern" to find custom resource analyzers. The filter, if required, can be given as a property of the service. For example to register an analyzer for WAR files, again using Declarative Services annotations:
@Component(property = "filter=(name=*.war)")
public class WarAnalyzer implements ResourceAnalyzer {
@@ -155,9 +88,9 @@ When used as an OSGi bundle, BIndex2 uses the "Whiteboard Pattern" to find custo
Resource Analyzers
==================
-BIndex2 is expected to be used primarily for analyzing and indexing OSGi bundles. However it is designed to be extensible to analyze any other kind of resource, since the OSGi Repository specification supports arbitrary resource types. It can also be extended to extract additional metadata from existing known types such as OSGi bundles.
+RepoIndex is expected to be used primarily for analyzing and indexing OSGi bundles. However it is designed to be extensible to analyze any other kind of resource, since the OSGi Repository specification supports arbitrary resource types. It can also be extended to extract additional metadata from existing known types such as OSGi bundles.
-For example, we may wish to extend BIndex2 to understand configuration files, script files, or native libraries. Alternatively we may wish to process custom extender headers from the MANIFEST.MF of OSGi bundles.
+For example, we may wish to extend RepoIndex to understand configuration files, script files, or native libraries. Alternatively we may wish to process custom extender headers from the MANIFEST.MF of OSGi bundles.
The `ResourceAnalyzer` interfaces defines a single method `analyzeResource`:
@@ -243,22 +176,21 @@ For example, to select files named either `foo.jar` or ending with the `.ear` ex
Packaging Resource Analyzers
----------------------------
-Resource analyzers should be packaged for delivery as OSGi bundles that register services under the `ResourceAnalyzer` interface. The BIndex2 command-line application uses a lightweight OSGi-like runtime called [PojoSR](https://code.google.com/p/pojosr/) to configure services, and looks for resource analyzers using the whiteboard pattern.
+Resource analyzers should be packaged for delivery as OSGi bundles that register services under the `ResourceAnalyzer` interface. The RepoIndex command-line application uses a lightweight OSGi-like runtime called [PojoSR](https://code.google.com/p/pojosr/) to configure services, and looks for resource analyzers using the whiteboard pattern.
-Note that if an analyzer implementation relies on Declarative Service to manage and register it as a service, then it will be necessary to place a Declarative Service implementation (also known as a Service Component Runtime or SCR) on the BIndex2 classpath. For example the Apache Felix SCR can be used as follows:
+Note that if an analyzer implementation relies on Declarative Service to manage and register it as a service, then it will be necessary to place a Declarative Service implementation (also known as a Service Component Runtime or SCR) on the RepoIndex classpath. For example the Apache Felix SCR can be used as follows:
- java -cp bindex2.jar;org.apache.felix.scr-1.6.0.jar;MyAnalyzer.jar \
+ java -cp org.osgi.impl.bundle.repoindex.cli.jar;org.apache.felix.scr-1.6.0.jar;MyAnalyzer.jar \
org.osgi.impl.bundle.bindex.cli.Index \
bundles/*.jar
Building from Source
====================
-BIndex can be built from source as follows:
+RepoIndex can be built from source as follows:
- $ cd bindex2.build
$ ant release
-The `bindex2.jar` file will be released into `release/bindex2/bindex2-VERSION.jar`.
+The JAR files will be released into `cnf/releaserepo/` and an index of the bundles will be generated into `cnf/releaserepo/index.xml`.
-To run all unit and integration tests, invoke `ant test`. The test report will be generated into `generated/test-reports/junit-noframes.html`.
+To run all unit and integration tests, invoke `ant test`. The test report will be generated into `generated/test-reports/junit-noframes.html` under each project.
View
8 build.xml
@@ -10,12 +10,16 @@
</sequential>
</macrodef>
+ <target name="clean">
+ <iterate target="clean"/>
+ </target>
+
<target name="build">
<ant dir="org.osgi.impl.bundle.repoindex.test" target="build"/>
</target>
- <target name="clean">
- <iterate target="clean"/>
+ <target name="release">
+ <iterate target="release"/>
</target>
<target name="junit" description="Run the unit tests">
View
6 ...rg/osgi/service/indexer/impl/BIndex2.java → .../osgi/service/indexer/impl/RepoIndex.java
@@ -30,7 +30,7 @@
import org.osgi.service.indexer.impl.util.Tag;
import org.osgi.service.log.LogService;
-public class BIndex2 implements ResourceIndexer {
+public class RepoIndex implements ResourceIndexer {
static final String REPOSITORY_INCREMENT_OVERRIDE = "-repository.increment.override";
@@ -42,11 +42,11 @@
private final List<Pair<ResourceAnalyzer, Filter>> analyzers = new LinkedList<Pair<ResourceAnalyzer,Filter>>();
- public BIndex2() {
+ public RepoIndex() {
this(new ConsoleLogSvc());
}
- public BIndex2(LogService log) {
+ public RepoIndex(LogService log) {
this.log = log;
this.bundleAnalyzer = new BundleAnalyzer(log);
View
4 org.osgi.impl.bundle.repoindex.lib/src/org/osgi/service/indexer/osgi/Activator.java
@@ -4,7 +4,7 @@
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import org.osgi.service.indexer.ResourceIndexer;
-import org.osgi.service.indexer.impl.BIndex2;
+import org.osgi.service.indexer.impl.RepoIndex;
public class Activator implements BundleActivator {
@@ -17,7 +17,7 @@ public void start(BundleContext context) throws Exception {
logTracker = new LogTracker(context);
logTracker.open();
- BIndex2 indexer = new BIndex2(logTracker);
+ RepoIndex indexer = new RepoIndex(logTracker);
analyzerTracker = new AnalyzerTracker(context, indexer, logTracker);
analyzerTracker.open();
View
6 org.osgi.impl.bundle.repoindex.lib/src/org/osgi/service/indexer/osgi/AnalyzerTracker.java
@@ -6,16 +6,16 @@
import org.osgi.framework.InvalidSyntaxException;
import org.osgi.framework.ServiceReference;
import org.osgi.service.indexer.ResourceAnalyzer;
-import org.osgi.service.indexer.impl.BIndex2;
+import org.osgi.service.indexer.impl.RepoIndex;
import org.osgi.service.log.LogService;
import org.osgi.util.tracker.ServiceTracker;
class AnalyzerTracker extends ServiceTracker {
- private final BIndex2 indexer;
+ private final RepoIndex indexer;
private final LogService log;
- public AnalyzerTracker(BundleContext context, BIndex2 indexer, LogService log) {
+ public AnalyzerTracker(BundleContext context, RepoIndex indexer, LogService log) {
super(context, ResourceAnalyzer.class.getName(), null);
this.indexer = indexer;
this.log = log;
View
36 org.osgi.impl.bundle.repoindex.lib/test/org/osgi/service/indexer/impl/TestIndexer.java
@@ -27,7 +27,7 @@
import org.osgi.service.indexer.Resource;
import org.osgi.service.indexer.ResourceAnalyzer;
import org.osgi.service.indexer.ResourceIndexer;
-import org.osgi.service.indexer.impl.BIndex2;
+import org.osgi.service.indexer.impl.RepoIndex;
import org.osgi.service.log.LogService;
public class TestIndexer extends TestCase {
@@ -105,11 +105,11 @@ public void testFragmentRequireSCR1_2() throws Exception {
}
private static void assertFragmentMatch(String expectedPath, String jarPath) throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
assertFragmentMatch(indexer, expectedPath, jarPath);
}
- private static void assertFragmentMatch(BIndex2 indexer, String expectedPath, String jarPath) throws Exception {
+ private static void assertFragmentMatch(RepoIndex indexer, String expectedPath, String jarPath) throws Exception {
StringWriter writer = new StringWriter();
indexer.indexFragment(Collections.singleton(new File(jarPath)), writer, null);
@@ -118,13 +118,13 @@ private static void assertFragmentMatch(BIndex2 indexer, String expectedPath, St
}
public void testEmptyIndex() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
ByteArrayOutputStream out = new ByteArrayOutputStream();
Set<File> files = Collections.emptySet();
Map<String, String> config = new HashMap<String, String>();
- config.put(BIndex2.REPOSITORY_INCREMENT_OVERRIDE, "0");
+ config.put(RepoIndex.REPOSITORY_INCREMENT_OVERRIDE, "0");
config.put(ResourceIndexer.REPOSITORY_NAME, "empty");
config.put(ResourceIndexer.PRETTY, "true");
indexer.index(files, out, config);
@@ -134,15 +134,15 @@ public void testEmptyIndex() throws Exception {
}
public void testFullIndex() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
ByteArrayOutputStream out = new ByteArrayOutputStream();
Set<File> files = new LinkedHashSet<File>();
files.add(new File("testdata/03-export.jar"));
files.add(new File("testdata/06-requirebundle.jar"));
Map<String, String> config = new HashMap<String, String>();
- config.put(BIndex2.REPOSITORY_INCREMENT_OVERRIDE, "0");
+ config.put(RepoIndex.REPOSITORY_INCREMENT_OVERRIDE, "0");
config.put(ResourceIndexer.REPOSITORY_NAME, "full-c+f");
indexer.index(files, out, config);
@@ -152,15 +152,15 @@ public void testFullIndex() throws Exception {
}
public void testFullIndexPrettyPrint() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
ByteArrayOutputStream out = new ByteArrayOutputStream();
Set<File> files = new LinkedHashSet<File>();
files.add(new File("testdata/03-export.jar"));
files.add(new File("testdata/06-requirebundle.jar"));
Map<String, String> config = new HashMap<String, String>();
- config.put(BIndex2.REPOSITORY_INCREMENT_OVERRIDE, "0");
+ config.put(RepoIndex.REPOSITORY_INCREMENT_OVERRIDE, "0");
config.put(ResourceIndexer.REPOSITORY_NAME, "full-c+f");
config.put(ResourceIndexer.PRETTY, "true");
indexer.index(files, out, config);
@@ -170,7 +170,7 @@ public void testFullIndexPrettyPrint() throws Exception {
}
public void testAddAnalyzer() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(new WibbleAnalyzer(), null);
StringWriter writer = new StringWriter();
@@ -185,7 +185,7 @@ public void testAddAnalyzer() throws Exception {
}
public void testAddAnalyzerWithFilter() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(new WibbleAnalyzer(), FrameworkUtil.createFilter("(location=*sion.jar)"));
StringWriter writer = new StringWriter();
@@ -200,7 +200,7 @@ public void testAddAnalyzerWithFilter() throws Exception {
}
public void testRootInSubdirectory() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
Map<String, String> props = new HashMap<String, String>();
props.put(ResourceIndexer.ROOT_URL, new File("testdata").getAbsoluteFile().toURI().toURL().toString());
@@ -213,7 +213,7 @@ public void testRootInSubdirectory() throws Exception {
}
public void testRootInSubSubdirectory() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
Map<String, String> props = new HashMap<String, String>();
props.put(ResourceIndexer.ROOT_URL, new File("testdata").getAbsoluteFile().toURI().toURL().toString());
@@ -234,7 +234,7 @@ public void analyzeResource(Resource resource, List<Capability> capabilities, Li
ResourceAnalyzer goodAnalyzer = mock(ResourceAnalyzer.class);
LogService log = mock(LogService.class);
- BIndex2 indexer = new BIndex2(log);
+ RepoIndex indexer = new RepoIndex(log);
indexer.addAnalyzer(badAnalyzer, null);
indexer.addAnalyzer(goodAnalyzer, null);
@@ -255,7 +255,7 @@ public void analyzeResource(Resource resource, List<Capability> capabilities, Li
public void testBundleOutsideRootDirectory() throws Exception {
LogService log = mock(LogService.class);
- BIndex2 indexer = new BIndex2(log);
+ RepoIndex indexer = new RepoIndex(log);
Map<String, String> props = new HashMap<String, String>();
props.put(ResourceIndexer.ROOT_URL, new File("testdata/subdir").getAbsoluteFile().toURI().toURL().toString());
@@ -268,7 +268,7 @@ public void testBundleOutsideRootDirectory() throws Exception {
public void testRemoveDisallowed() throws Exception {
LogService log = mock(LogService.class);
- BIndex2 indexer = new BIndex2(log);
+ RepoIndex indexer = new RepoIndex(log);
indexer.addAnalyzer(new NaughtyAnalyzer(), null);
Map<String, String> props = new HashMap<String, String>();
@@ -284,7 +284,7 @@ public void testRecogniseFelixSCR() throws Exception {
Properties props = new Properties();
props.load(new FileInputStream("testdata/known-bundles.properties"));
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(new KnownBundleAnalyzer(props), FrameworkUtil.createFilter("(name=*)"));
assertFragmentMatch(indexer, "testdata/org.apache.felix.scr-1.6.0.xml", "testdata/org.apache.felix.scr-1.6.0.jar");
}
@@ -293,7 +293,7 @@ public void testMacroExpansion() throws Exception {
Properties props = new Properties();
props.load(new FileInputStream("testdata/known-bundles.properties"));
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(new KnownBundleAnalyzer(props), FrameworkUtil.createFilter("(name=*)"));
assertFragmentMatch(indexer, "testdata/org.apache.felix.eventadmin.xml", "testdata/org.apache.felix.eventadmin-1.2.14.jar");
}
View
8 ...gi.impl.bundle.repoindex.test/src/org/example/tests/standalone/TestStandaloneLibrary.java
@@ -13,13 +13,13 @@
import org.osgi.framework.FrameworkUtil;
import org.osgi.service.indexer.ResourceIndexer;
-import org.osgi.service.indexer.impl.BIndex2;
+import org.osgi.service.indexer.impl.RepoIndex;
import org.osgi.service.indexer.impl.KnownBundleAnalyzer;
public class TestStandaloneLibrary extends TestCase {
public void testBasicServiceInvocation() throws Exception {
- ResourceIndexer indexer = new BIndex2();
+ ResourceIndexer indexer = new RepoIndex();
StringWriter writer = new StringWriter();
File tempDir = createTempDir();
@@ -35,7 +35,7 @@ public void testBasicServiceInvocation() throws Exception {
}
public void testKnownBundleRecognition() throws Exception {
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(new KnownBundleAnalyzer(), FrameworkUtil.createFilter("(name=*)"));
StringWriter writer = new StringWriter();
@@ -58,7 +58,7 @@ public void testKnownBundlesExtra() throws Exception {
KnownBundleAnalyzer knownBundlesAnalyzer = new KnownBundleAnalyzer();
knownBundlesAnalyzer.setKnownBundlesExtra(extras);
- BIndex2 indexer = new BIndex2();
+ RepoIndex indexer = new RepoIndex();
indexer.addAnalyzer(knownBundlesAnalyzer, FrameworkUtil.createFilter("(name=*)"));
StringWriter writer = new StringWriter();

0 comments on commit 069c9cd

Please sign in to comment.
Something went wrong with that request. Please try again.