Mailing-List: contact commits-help@aries.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@aries.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: davidb@apache.org
To: commits@aries.apache.org
Message-Id: <5bb97eb53f9c47cfbc5403cd13ffdc9b@git.apache.org>
Subject: aries-containers git commit: Add some javadoc to ServiceConfig.
Date: Fri, 26 May 2017 15:37:57 +0000 (UTC)
archived-at: Fri, 26 May 2017 15:37:59 -0000

Repository: aries-containers
Updated Branches:
  refs/heads/master 56d7ed550 -> 8d71dfef4


Add some javadoc to ServiceConfig.


Project: http://git-wip-us.apache.org/repos/asf/aries-containers/repo
Commit: http://git-wip-us.apache.org/repos/asf/aries-containers/commit/8d71dfef
Tree: http://git-wip-us.apache.org/repos/asf/aries-containers/tree/8d71dfef
Diff: http://git-wip-us.apache.org/repos/asf/aries-containers/diff/8d71dfef

Branch: refs/heads/master
Commit: 8d71dfef46d1d096d43300e4e308b0aae92dc4d6
Parents: 56d7ed5
Author: David Bosschaert <davidb@apache.org>
Authored: Fri May 26 16:37:42 2017 +0100
Committer: David Bosschaert <davidb@apache.org>
Committed: Fri May 26 16:37:42 2017 +0100

----------------------------------------------------------------------
 .../apache/aries/containers/ServiceConfig.java  | 112 ++++++++++++++++++-
 1 file changed, 108 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/aries-containers/blob/8d71dfef/containers-api/src/main/java/org/apache/aries/containers/ServiceConfig.java
----------------------------------------------------------------------
diff --git a/containers-api/src/main/java/org/apache/aries/containers/ServiceConfig.java b/containers-api/src/main/java/org/apache/aries/containers/ServiceConfig.java
index fe38e50..c7a91ab 100644
--- a/containers-api/src/main/java/org/apache/aries/containers/ServiceConfig.java
+++ b/containers-api/src/main/java/org/apache/aries/containers/ServiceConfig.java
@@ -19,12 +19,22 @@
 package org.apache.aries.containers;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
 import org.osgi.annotation.versioning.ProviderType;
 
+/**
+ * This class defines a service and it's settings. An instance is created via the
+ * {@link Builder} and is immutable. For example to create a service for the Apache
+ * Web Server docker image:
+ * <pre>
+ * ServiceConfig sc = ServiceConfig.builder("myservice", "httpd").
+ *   cpu(0.5).memory(64).port(80).build();
+ * </pre>
+ */
 @ProviderType
 public class ServiceConfig {
     private final String[] commandLine;
@@ -38,49 +48,74 @@ public class ServiceConfig {
     private final double requestedMemory; // in MiB
     private final String serviceName;
 
-
     private ServiceConfig(String[] commandLine, String containerImage, List<Integer> containerPorts, String entryPoint,
             Map<String, String> envVars, double requestedCPUunits, int requestedInstances, double requestedMemory,
             String serviceName) {
         this.commandLine = commandLine;
         this.containerImage = containerImage;
-        this.containerPorts = containerPorts;
+        this.containerPorts = Collections.unmodifiableList(containerPorts);
         this.entryPoint = entryPoint;
-        this.envVars = envVars;
+        this.envVars = Collections.unmodifiableMap(envVars);
         this.requestedCPUunits = requestedCPUunits;
         this.requestedInstances = requestedInstances;
         this.requestedMemory = requestedMemory;
         this.serviceName = serviceName;
     }
 
+    /**
+     * @return The command line to be used by the container. See also {@link #getEntryPoint()}.
+     */
     public String[] getCommandLine() {
-        return commandLine;
+        return commandLine.clone();
     }
 
+    /**
+     * @return The name of the container image.
+     */
     public String getContainerImage() {
         return containerImage;
     }
 
+    /**
+     * @return A list of the ports exposed externally.
+     */
     public List<Integer> getContainerPorts() {
         return containerPorts;
     }
 
+    /**
+     * @return The entry point to be used with the image. Together with the {@link #getCommandLine()}
+     * this defines the process run in the image.
+     */
     public String getEntryPoint() {
         return entryPoint;
     }
 
+    /**
+     * @return A map containing all the environment variables to be set.
+     */
     public Map<String, String> getEnvVars() {
         return envVars;
     }
 
+    /**
+     * @return The cpu units required for each container running this service.
+     */
     public double getRequestedCpuUnits() {
         return requestedCPUunits;
     }
 
+    /**
+     * @return The number of replica containers requested for the service.
+     */
     public int getRequestedInstances() {
         return requestedInstances;
     }
 
+    /**
+     * @return The amount of memory require for each container running the service.
+     * Specified in million bytes (MiB).
+     */
     public double getRequestedMemory() {
         return requestedMemory;
     }
@@ -93,10 +128,19 @@ public class ServiceConfig {
         return serviceName;
     }
 
+    /**
+     * Obtain a service configuration builder.
+     * @param serviceName The name for the service. This name should be unique in the
+     * deployment, should be alphanum only and should not exceed 32 characters.
+     * @param containerImage The container image to use. When using docker, this is
+     * the docker image that should be used.
+     * @return A service configuration builder
+     */
     public static Builder builder(String serviceName, String containerImage) {
         return new Builder(serviceName, containerImage);
     }
 
+    /** A builder for service configurations */
     @ProviderType
     public static class Builder {
         private String containerImage;
@@ -114,47 +158,107 @@ public class ServiceConfig {
             this.containerImage = containerImage;
         }
 
+        /** The command line for the service. Also note that some images may need
+         * an {@link #entryPoint(String)} specified in order to change behaviour.
+         *
+         * @param commandLine The command line to use.
+         * @return the current builder for further building.
+         */
         public Builder commandLine(String ... commandLine) {
             this.commandLine = commandLine;
             return this;
         }
 
+        /**
+         * The requested CPU for the service.
+         *
+         * @param requestedCpuUnits The requested CPU in CPU fractional units.
+         * @return the current builder for further building.
+         */
         public Builder cpu(double requestedCpuUnits) {
             this.requestedCpuUnits = requestedCpuUnits;
             return this;
         }
 
+        /**
+         * The entrypoint to use. Effectively the entrypoint together with the
+         * commandline defines the process launched by the container.
+         *
+         * @param entryPoint The entry point to use.
+         * @return the current builder for further building.
+         */
         public Builder entryPoint(String entryPoint) {
             this.entryPoint = entryPoint;
             return this;
         }
 
+        /**
+         * Specify an environment variable. The variable is added to previously
+         * specified environment variables and this builder method can be called
+         * multiple times.
+         *
+         * @param name The variable name.
+         * @param value The variable value.
+         * @return the current builder for further building.
+         */
         public Builder env(String name, String value) {
             this.envMap.put(name, value);
             return this;
         }
 
+        /**
+         * Set the environment variables to the provided map. This will replace
+         * any previously specified environment variables.
+         *
+         * @param envMap The map of environment variables.
+         * @return the current builder for further building.
+         */
         public Builder env(Map<String, String> envMap) {
             this.envMap.clear();
             this.envMap.putAll(envMap);
             return this;
         }
 
+        /**
+         * Specify the number of container instances required for this service.
+         * The container will be deployed as many times as specified here.
+         *
+         * @param requestedInstances The number of required instances.
+         * @return the current builder for further building.
+         */
         public Builder instances(int requestedInstances) {
             this.requestedInstances = requestedInstances;
             return this;
         }
 
+        /**
+         * Specify the required amount of memory in million bytes (MiB).
+         *
+         * @param requestedMemory The amount of memory required of a container.
+         * @return the current builder for further building.
+         */
         public Builder memory(double requestedMemory) {
             this.requestedMemory = requestedMemory;
             return this;
         }
 
+        /**
+         * Specify an external port to be exposed by the container. When a container
+         * exposes multiple ports, call this builder method multiple times.
+         *
+         * @param port The port to be exposed externally.
+         * @return the current builder for further building.
+         */
         public Builder port(int port) {
             this.ports.add(port);
             return this;
         }
 
+        /**
+         * Build the configuration from the information gathered in the builder.
+         *
+         * @return An immutable service configuration.
+         */
         public ServiceConfig build() {
             return new ServiceConfig(commandLine, containerImage, ports, entryPoint,
                     envMap, requestedCpuUnits, requestedInstances, requestedMemory,