#57 Make API more concise

* use symmetric naming for resource and class operations
* add nullability annotations
* streamline names and javadoc
* rename RawBuilder to AbstractBuilder and AsyncRawBuilder to RawBuilder
* make BndBuilder extend AbstractBuilder and drop inner builder support

pom.xml

@@ -282,6 +282,13 @@
       <version>2.2.6</version>
       <scope>test</scope>
     </dependency>
+    <!-- nullability annotations -->
+    <dependency>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>24.0.1</version>
+      <scope>provided</scope>
+    </dependency>
     <!-- logging -->
     <dependency>
       <groupId>org.slf4j</groupId>

src/main/java/org/ops4j/pax/tinybundles/Builder.java

@@ -21,12 +21,11 @@
 import java.net.URL;
 import java.util.Map;
 
+import org.jetbrains.annotations.NotNull;
 import org.osgi.annotation.versioning.ProviderType;
 
 /**
- * Builder.
- * Implementors should be stateless so builders can be shared.
- * Usually the "build" action is an atomic, functional operation.
+ * Builder for TinyBundles. The builder is used by {@link TinyBundle} internally.
  *
  * @author Toni Menzel (tonit)
  * @since Apr 20, 2009
@@ -35,12 +34,13 @@
 public interface Builder {
 
     /**
-     * perform the actual build.
+     * Builds the bundle with given resources and headers.
      *
-     * @param resources resources to be considered in the build.
-     * @param headers   headers to be considered in the build
-     * @return an {@link InputStream} containing built assembly (usually a jar/bundle in this context)
+     * @param resources the resources to be considered in the build
+     * @param headers   the headers to be considered in the build
+     * @return the built assembly (bundle or jar)
      */
-    InputStream build(final Map<String, URL> resources, final Map<String, String> headers);
+    @NotNull
+    InputStream build(@NotNull final Map<String, URL> resources, @NotNull final Map<String, String> headers);
 
 }

src/main/java/org/ops4j/pax/tinybundles/TinyBundle.java

@@ -19,12 +19,16 @@
 
 import java.io.InputStream;
 import java.net.URL;
+import java.util.jar.JarInputStream;
+import java.util.jar.Manifest;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.osgi.annotation.versioning.ProviderType;
+import org.osgi.framework.BundleActivator;
 
 /**
- * Main type when making bundles with the {@link TinyBundles} library.
- * Get an instance from {@link TinyBundles} Factory, add resources and call {@link #build()} to go to the final step.
+ * TinyBundle provides a fluent API to create and modify OSGi bundles on the fly.
  *
  * @author Toni Menzel (tonit)
  * @since Apr 9, 2009
@@ -33,121 +37,142 @@
 public interface TinyBundle {
 
     /**
-     * Add a resource to the current bundle (to be built).
+     * Adds the class into the bundle and sets it as bundle activator.
      *
-     * @param name    final path inside the jar
-     * @param content content to be copied into bundle.
-     * @return *this*
+     * @param activator the bundle activator
+     * @return the tiny bundle
      */
-    TinyBundle add(final String name, final URL content);
+    @NotNull
+    TinyBundle activator(@NotNull final Class<? extends BundleActivator> activator);
 
     /**
-     * Add a resource to the current bundle (to be built).
+     * Sets the bundle symbolic name.
      *
-     * @param name    final path inside the jar
-     * @param content content to be copied into bundle.
-     * @return *this*
+     * @param symbolicName the bundle symbolic name
+     * @return the tiny bundle
      */
-    TinyBundle add(final String name, final InputStream content);
+    @NotNull
+    TinyBundle symbolicName(@NotNull final String symbolicName);
 
     /**
-     * Add a class to the current bundle. Uses InnerClassStrategy.ALL
+     * Adds the resource into the bundle.
      *
-     * @param clazz content to be copied into bundle.
-     * @return {@literal this}
+     * @param path     the path where the resource gets stored in the bundle
+     * @param resource the resource to be added
+     * @return the tiny bundle
      */
-    TinyBundle add(final Class<?> clazz);
+    @NotNull
+    TinyBundle addResource(@NotNull final String path, @NotNull final URL resource);
 
     /**
-     * Add a class to the current bundle.
+     * Adds the resource into the bundle.
      *
-     * @param clazz
+     * @param path     the path where the resource gets stored in the bundle
+     * @param resource the resource to be added
+     * @return the tiny bundle
      */
-    TinyBundle add(final Class<?> clazz, final InnerClassStrategy strategy);
+    @NotNull
+    TinyBundle addResource(@NotNull final String path, @NotNull final InputStream resource);
 
     /**
-     * Add a class to the current bundle and set it as Activator
+     * Removes a resource from the bundle.
      *
-     * @param activator
+     * @param path the path of the to be removed resource
+     * @return the tiny bundle
      */
-    TinyBundle activator(final Class<?> activator);
+    @NotNull
+    TinyBundle removeResource(@NotNull final String path);
 
     /**
-     * Set symbolic name of bundle
+     * Adds the class into the bundle with default {@link InnerClassStrategy#ALL} strategy.
      *
-     * @param name
+     * @param clazz the class to be added
+     * @return the tiny bundle
      */
-    TinyBundle symbolicName(final String name);
+    @NotNull
+    TinyBundle addClass(@NotNull final Class<?> clazz);
 
     /**
-     * remove a class to the current bundle.
+     * Adds the class into the bundle.
      *
-     * @param clazz class to be removed
-     * @return *this*
+     * @param clazz    the class to be added
+     * @param strategy the inner class strategy for the given class
+     * @return the tiny bundle
      */
-    TinyBundle remove(final Class<?> clazz);
+    @NotNull
+    TinyBundle addClass(@NotNull final Class<?> clazz, @NotNull final InnerClassStrategy strategy);
 
     /**
-     * When you are done adding stuff to *this* you can call this method to go to next step.
+     * Removes the class from the bundle.
      *
-     * @param builder builder to be used.
-     * @return Next step in the bundle making process.
+     * @param clazz the class to be removed
+     * @return the tiny bundle
      */
-    InputStream build(final Builder builder);
+    @NotNull
+    TinyBundle removeClass(@NotNull final Class<?> clazz);
 
     /**
-     * Build bundle with default builder.
+     * Sets the {@link Manifest}  header.
      *
-     * @return Next step in the bundle making process.
+     * @param name  the header name
+     * @param value the header value
+     * @return the tiny bundle
      */
-    InputStream build();
+    @NotNull
+    TinyBundle setHeader(@NotNull final String name, @NotNull final String value);
 
     /**
-     * Set header values that go into the Manifest.
+     * Gets the {@link Manifest} header value for the given name.
      *
-     * @param key   a key
-     * @param value a value
-     * @return {@literal this}
+     * @param name the header name
+     * @return the header value or null if header is not present
      */
-    TinyBundle set(final String key, final String value);
+    @Nullable
+    String getHeader(@NotNull final String name);
 
     /**
-     * Remove a previously added resource.
-     * Usually useful if you loaded an existing bundle into {@link TinyBundles} before.
+     * Removes the {@link Manifest} header.
      *
-     * @param key a key as String
-     * @return {@literal this}
+     * @param name the name of the to be removed header
+     * @return the tiny bundle
      */
-    TinyBundle removeResource(final String key);
+    @NotNull
+    TinyBundle removeHeader(@NotNull final String name);
 
     /**
-     * Remove a previously added header.
-     * Usually useful if you loaded an existing bundle into {@link TinyBundles} before.
+     * Reads an existing bundle or jar into this TinyBundle.
      *
-     * @param key a key as String
-     * @return {@literal this}
+     * @param jar the stream of JarInputStream
+     * @return the tiny bundle
      */
-    TinyBundle removeHeader(final String key);
+    @NotNull
+    TinyBundle readIn(@NotNull final JarInputStream jar);
 
     /**
-     * Read an existing bundle or jar into TinyBundles for modification.
+     * Reads an existing jar or bundle into this tiny bundle.
      *
-     * @param inputStream stream of JarInputStream
-     * @return {@literal this}
+     * @param jar         the source jar or bundle
+     * @param skipContent true to read jar content also, false to read {@link Manifest} only
+     * @return the tiny bundle
      */
-    TinyBundle read(final InputStream inputStream);
+    @NotNull
+    TinyBundle readIn(@NotNull final JarInputStream jar, final boolean skipContent);
 
     /**
-     * Read an existing bundle or jar into TinyBundles for modification.
+     * Builds the bundle with default bnd {@link Builder}.
      *
-     * @param input stream of JarInputStream
-     * @return {@literal this}
+     * @return the built bundle
      */
-    TinyBundle read(final InputStream input, final boolean readContent);
+    @NotNull
+    InputStream build();
 
     /**
-     * Get header value.
+     * Builds the bundle with given {@link Builder}.
+     *
+     * @param builder the builder to be used for building
+     * @return the built bundle
      */
-    String getHeader(final String key);
+    @NotNull
+    InputStream build(@NotNull final Builder builder);
 
 }

src/main/java/org/ops4j/pax/tinybundles/TinyBundles.java

@@ -27,8 +27,7 @@
 import org.osgi.framework.ServiceReference;
 
 /**
- * Statically usable TinyBundles API.
- * Usually the entry point for using TinyBundles.
+ * Statically usable TinyBundles factory.
  *
  * @author Toni Menzel
  * @since 1.0.0
@@ -54,42 +53,37 @@ private static TinyBundlesFactory factory() {
     }
 
     /**
-     * {@see #bundle(BuildableBundle, org.ops4j.store.Store)}
+     * Creates a new {@link TinyBundle}.
      *
-     * @return a new instance of {@link TinyBundle}.
+     * @return the new tiny bundle
      */
     public static TinyBundle bundle() {
         return factory().bundle();
     }
 
     /**
-     * Start with a fresh bundle with this factory method.
-     * You can then chain method calls thanks to the humane nature of {@link TinyBundle} interface.
+     * Creates a new {@link TinyBundle}.
      *
-     * @param store cache backend
-     * @return a new instance of {@link TinyBundle}.
+     * @param store the cache backend to use
+     * @return the new tiny bundle
      */
     public static TinyBundle bundle(final Store<InputStream> store) {
         return factory().bundle(store);
     }
 
     /**
-     * @param inner builder when using bnd builder.
-     * @return a builder to be used with {@link TinyBundle#build(Builder)} using bnd with given builder.
-     */
-    public static Builder bndBuilder(final Builder inner) {
-        return factory().bndBuilder(inner);
-    }
-
-    /**
-     * @return a builder to be used with {@link TinyBundle#build(Builder)} using bnd with raw builder.
+     * Creates a new bnd builder.
+     *
+     * @return the new bnd builder
      */
     public static Builder bndBuilder() {
-        return factory().bndBuilder(rawBuilder());
+        return factory().bndBuilder();
     }
 
     /**
-     * @return a builder to be used with {@link TinyBundle#build(Builder)} using no extra manifest computation logic.
+     * Creates a new raw builder.
+     *
+     * @return the new raw builder
      */
     public static Builder rawBuilder() {
         return factory().rawBuilder();

src/main/java/org/ops4j/pax/tinybundles/TinyBundlesFactory.java

@@ -19,20 +19,47 @@
 
 import java.io.InputStream;
 
+import org.jetbrains.annotations.NotNull;
 import org.ops4j.store.Store;
 import org.osgi.annotation.versioning.ProviderType;
 
+/**
+ * TinyBundles factory (OSGi) service.
+ */
 @ProviderType
 public interface TinyBundlesFactory {
 
+    /**
+     * Creates a new {@link TinyBundle}.
+     *
+     * @return the new tiny bundle
+     */
+    @NotNull
     TinyBundle bundle();
 
-    TinyBundle bundle(final Store<InputStream> store);
-
-    Builder rawBuilder();
+    /**
+     * Creates a new {@link TinyBundle}.
+     *
+     * @param store the cache backend to use
+     * @return the new tiny bundle
+     */
+    @NotNull
+    TinyBundle bundle(@NotNull final Store<InputStream> store);
 
+    /**
+     * Creates a new bnd builder.
+     *
+     * @return the new bnd builder
+     */
+    @NotNull
     Builder bndBuilder();
 
-    Builder bndBuilder(final Builder inner);
+    /**
+     * Creates a new raw builder.
+     *
+     * @return the new raw builder
+     */
+    @NotNull
+    Builder rawBuilder();
 
 }