Improve Javadocs

git-svn-id: https://svn.argeo.org/slc/trunk@3969 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc

diff --git a/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/ResourceDistribution.java b/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/ResourceDistribution.java
index 224d0054a396962b35c89b80cf27bd46be279cb3..37c72601edd66fd7eb22fd2224be094b833c9219 100644 (file)
--- a/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/ResourceDistribution.java
+++ b/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/ResourceDistribution.java
@@ -24,6 +24,7 @@ import org.argeo.slc.StreamReadable;
 import org.argeo.slc.build.Distribution;
 import org.springframework.core.io.Resource;
 
+/** A software distribution archive accessible via a {@link Resource}. */
 public class ResourceDistribution implements Distribution, StreamReadable {
        private Resource resource;
 

diff --git a/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/VersionedResourceDistribution.java b/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/VersionedResourceDistribution.java
index 6acca71fe2708440c56f83f436ec20ce21d9614c..2cf454f6bce87b06313abbaedc95cb573555d292 100644 (file)
--- a/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/VersionedResourceDistribution.java
+++ b/runtime/org.argeo.slc.core/src/main/java/org/argeo/slc/core/build/VersionedResourceDistribution.java
@@ -19,6 +19,10 @@ package org.argeo.slc.core.build;
 import org.argeo.slc.build.NameVersion;
 import org.springframework.core.io.Resource;
 
+/**
+ * The distribution of a software package (jar, zip, RPM, etc.) which is
+ * versioned. The archive itself is accessible via a {@link Resource}.
+ */
 public class VersionedResourceDistribution extends ResourceDistribution
                implements NameVersion {
        private String name;

diff --git a/runtime/org.argeo.slc.specs/src/main/java/org/argeo/slc/build/NameVersion.java b/runtime/org.argeo.slc.specs/src/main/java/org/argeo/slc/build/NameVersion.java
index 7623a102b44b3c72955f8009020c299b23210990..0be583be4c0aeb7e9b266b99573bc5895aab3466 100644 (file)
--- a/runtime/org.argeo.slc.specs/src/main/java/org/argeo/slc/build/NameVersion.java
+++ b/runtime/org.argeo.slc.specs/src/main/java/org/argeo/slc/build/NameVersion.java
@@ -16,8 +16,14 @@
 
 package org.argeo.slc.build;
 
+/**
+ * Abstraction of a name / version pair, typically used as coordinates for a
+ * software module either deployed or packaged as an archive.
+ */
 public interface NameVersion {
+       /** The name of the component. */
        public String getName();
 
+       /** The version of teh component. */
        public String getVersion();
 }

diff --git a/runtime/org.argeo.slc.support.osgi/src/main/java/org/argeo/slc/osgi/OsgiBundle.java b/runtime/org.argeo.slc.support.osgi/src/main/java/org/argeo/slc/osgi/OsgiBundle.java
index 7cce2308350f9d7000d932ce120be25e0bb9d813..ede0986a2a0e9aa343e8cf0856f687e8a8e77309 100644 (file)
--- a/runtime/org.argeo.slc.support.osgi/src/main/java/org/argeo/slc/osgi/OsgiBundle.java
+++ b/runtime/org.argeo.slc.support.osgi/src/main/java/org/argeo/slc/osgi/OsgiBundle.java
@@ -26,8 +26,12 @@ import org.argeo.slc.deploy.TargetData;
 import org.argeo.slc.process.RealizedFlow;
 import org.osgi.framework.Bundle;
 import org.osgi.framework.Constants;
+import org.springframework.core.io.Resource;
 
+/** A deployed OSGi bundle. */
 public class OsgiBundle extends BasicNameVersion implements Module {
+       private static final long serialVersionUID = -1970854723780452072L;
+
        private ResourceDistribution distribution;
 
        private Long internalBundleId;
@@ -52,6 +56,17 @@ public class OsgiBundle extends BasicNameVersion implements Module {
                internalBundleId = bundle.getBundleId();
        }
 
+       /**
+        * Initialize from a {@link RealizedFlow}.
+        * 
+        * @deprecated introduce an unnecessary dependency. TODO: create a separate
+        *             helper.
+        */
+       public OsgiBundle(RealizedFlow realizedFlow) {
+               super(realizedFlow.getModuleName(), realizedFlow.getModuleVersion());
+       }
+
+       /** Utility to avoid NPE. */
        private static String getVersionSafe(Bundle bundle) {
                Object versionObj = bundle.getHeaders().get(Constants.BUNDLE_VERSION);
                if (versionObj != null)
@@ -60,26 +75,35 @@ public class OsgiBundle extends BasicNameVersion implements Module {
                        return null;
        }
 
-       public OsgiBundle(RealizedFlow realizedFlow) {
-               super(realizedFlow.getModuleName(), realizedFlow.getModuleVersion());
-       }
-
+       /** Unique deployed system id. TODO: use internal bundle id when available? */
        public String getDeployedSystemId() {
                return getName() + ":" + getVersion();
        }
 
+       /**
+        * OSGi bundle are self-contained and do not require additional deployment
+        * data.
+        * 
+        * @return always null
+        */
        public DeploymentData getDeploymentData() {
-               throw new UnsupportedOperationException();
+               return null;
        }
 
+       /** The related distribution. */
        public Distribution getDistribution() {
                return distribution;
        }
 
+       /**
+        * The related distribution, a jar file with OSGi metadata referenced by a
+        * {@link Resource}.
+        */
        public ResourceDistribution getResourceDistribution() {
                return distribution;
        }
 
+       /** TODO: reference the {@link OsgiRuntime} as target data? */
        public TargetData getTargetData() {
                throw new UnsupportedOperationException();
        }
@@ -89,8 +113,8 @@ public class OsgiBundle extends BasicNameVersion implements Module {
        }
 
        /**
-        * To be used for optimization when looking in the bundle context. Can
-        * therefore be null.
+        * Bundle ID used by the OSGi runtime. To be used for optimization when
+        * looking in the bundle context. Can therefore be null.
         */
        public Long getInternalBundleId() {
                return internalBundleId;
@@ -101,6 +125,7 @@ public class OsgiBundle extends BasicNameVersion implements Module {
                this.internalBundleId = internalBundleId;
        }
 
+       /** Value of the <code>Bundle-Name</code> directive. */
        public String getLabel() {
                return label;
        }
@@ -109,6 +134,7 @@ public class OsgiBundle extends BasicNameVersion implements Module {
                this.label = label;
        }
 
+       /** Value of the <code>Bundle-Description</code> directive. */
        public String getDescription() {
                return description;
        }