Repository: karaf Updated Branches: refs/heads/master 9d136eb44 -> 8a1e7574d
http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/impl/console/standalone/Main.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/impl/console/standalone/Main.java b/shell/core/src/main/java/org/apache/karaf/shell/impl/console/standalone/Main.java index 681f6ac..dd9ed00 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/impl/console/standalone/Main.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/impl/console/standalone/Main.java @@ -62,8 +62,8 @@ public class Main { /** * Use this method when the shell is being executed as a top level shell. * - * @param args - * @throws Exception + * @param args the arguments. + * @throws Exception in case of a failure. */ public void run(String args[]) throws Exception { @@ -171,13 +171,13 @@ public class Main { /** * Allow sub classes of main to change the ConsoleImpl implementation used. * - * @param sessionFactory - * @param in - * @param out - * @param err - * @param terminal - * @return - * @throws Exception + * @param sessionFactory the session factory. + * @param in the input stream (console std in). + * @param out the output stream (console std out). + * @param err the error stream (console std err). + * @param terminal the terminal. + * @return the created session. + * @throws Exception if something goes wrong during session creation. */ protected Session createSession(SessionFactory sessionFactory, InputStream in, PrintStream out, PrintStream err, Terminal terminal) throws Exception { return sessionFactory.create(in, out, err, terminal, null, null); @@ -192,6 +192,8 @@ public class Main { /** * Sub classes can override so that their registered commands do not conflict with the default shell * implementation. + * + * @return the location of the discovery resource. */ public String getDiscoveryResource() { return "META-INF/services/org/apache/karaf/shell/commands"; @@ -233,10 +235,12 @@ public class Main { } /** - * Returns whether or not we are in multi-scope mode. - * <p/> - * The default mode is multi-scoped where we prefix commands by their scope. If we are in single - * scoped mode then we don't use scope prefixes when registering or tab completing commands. + * <p>Returns whether or not we are in multi-scope mode.</p> + * + * <p>The default mode is multi-scoped where we prefix commands by their scope. If we are in single + * scoped mode then we don't use scope prefixes when registering or tab completing commands.</p> + * + * @return true if the console is multi-scope, false else. */ public boolean isMultiScopeMode() { return true; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/NameScoping.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/NameScoping.java b/shell/core/src/main/java/org/apache/karaf/shell/support/NameScoping.java index fc3c5ed..4249fed 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/NameScoping.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/NameScoping.java @@ -17,7 +17,6 @@ */ package org.apache.karaf.shell.support; - import org.apache.karaf.shell.api.console.Session; /** @@ -28,8 +27,12 @@ public class NameScoping { public static final String MULTI_SCOPE_MODE_KEY = "MULTI_SCOPE_MODE"; /** - * Returns the name of the command which can omit the global scope prefix if the command starts with the - * same prefix as the current application + * Return the name of the command which can omit the global scope prefix if the command starts with the + * same prefix as the current application. + * + * @param session the command session. + * @param key the command key. + * @return the command without the prefix. */ public static String getCommandNameWithoutGlobalPrefix(Session session, String key) { if (!isMultiScopeMode(session)) { @@ -47,7 +50,11 @@ public class NameScoping { } /** - * Returns true if the given scope is the global scope so that it can be hidden from help messages + * Return true if the given scope is the global scope so that it can be hidden from help messages. + * + * @param session the command session. + * @param scope the command scope. + * @return true if the command scope is global, false else. */ public static boolean isGlobalScope(Session session, String scope) { if (session == null) @@ -63,8 +70,11 @@ public class NameScoping { } /** - * Returns true if we are in multi-scope mode (the default) or if we are in single scope mode which means we - * avoid prefixing commands with their scope + * Return true if we are in multi-scope mode (the default) or if we are in single scope mode which means we + * avoid prefixing commands with their scope. + * + * @param session the command session. + * @return true if the command is multi-scoped, false else. */ public static boolean isMultiScopeMode(Session session) { if (session == null) http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/ShellUtil.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/ShellUtil.java b/shell/core/src/main/java/org/apache/karaf/shell/support/ShellUtil.java index 405f608..3a9ba0e 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/ShellUtil.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/ShellUtil.java @@ -101,11 +101,11 @@ public class ShellUtil { } /** - * Check if a bundle is a system bundle (start level < 50) + * Check if a bundle is a system bundle (start level minor than 50). * - * @param bundleContext - * @param bundle - * @return true if the bundle has start level minor than 50 + * @param bundleContext the current bundle context. + * @param bundle the bundle to check. + * @return true if the bundle has start level minor than 50. */ public static boolean isASystemBundle(BundleContext bundleContext, Bundle bundle) { int level = bundle.adapt(BundleStartLevel.class).getStartLevel(); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/completers/FileCompleter.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/completers/FileCompleter.java b/shell/core/src/main/java/org/apache/karaf/shell/support/completers/FileCompleter.java index c200f4c..4a96d52 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/completers/FileCompleter.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/completers/FileCompleter.java @@ -24,15 +24,14 @@ import org.apache.karaf.shell.api.console.CommandLine; import org.apache.karaf.shell.api.console.Completer; import org.apache.karaf.shell.api.console.Session; - /** - * A file name completer takes the buffer and issues a list of - * potential completions. - * <p/> - * This completer tries to behave as similar as possible to + * <p>A file name completer takes the buffer and issues a list of + * potential completions.</p> + * + * <p>This completer tries to behave as similar as possible to * <i>bash</i>'s file name completion (using GNU readline) - * with the following exceptions: - * <p/> + * with the following exceptions:</p> + * * <ul> * <li>Candidates that are directories will end with "/"</li> * <li>Wildcard regular expressions are not evaluated or replaced</li> http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/converter/ReifiedType.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/converter/ReifiedType.java b/shell/core/src/main/java/org/apache/karaf/shell/support/converter/ReifiedType.java index 6f89857..5a692ef 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/converter/ReifiedType.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/converter/ReifiedType.java @@ -30,10 +30,8 @@ package org.apache.karaf.shell.support.converter; * a subclass that provide type arguments should be respected. Blueprint * extender implementations can subclass this class and provide access to the * generics type graph if used in a conversion. Such a subclass must - * <em>reify<em> the different Java 5 <code>Type</code> instances into the + * <em>reify</em> the different Java 5 <code>Type</code> instances into the * reified form. That is, a form where the raw Class is available with its optional type arguments as Reified Types. - * - * @Immutable */ public class ReifiedType { final static ReifiedType ALL = new ReifiedType(Object.class); @@ -80,7 +78,7 @@ public class ReifiedType { * object is assignable to Object and therefore no conversion is then * necessary, this is compatible with older Javas than 5. For this reason, * the implementation in this class always returns the - * <code>Object<code> class, regardless of the given index. + * <code>Object</code> class, regardless of the given index. * * This method should be overridden by a subclass that provides access to * the generic information. @@ -96,7 +94,7 @@ public class ReifiedType { * * @param i * The index of the type argument - * @return <code>ReifiedType(Object.class)<code>, subclasses must override this and return the generic argument at index <code>i</code> + * @return <code>ReifiedType</code>, subclasses must override this and return the generic argument at index <code>i</code> */ public ReifiedType getActualTypeArgument(int i) { return ALL; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/table/HAlign.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/table/HAlign.java b/shell/core/src/main/java/org/apache/karaf/shell/support/table/HAlign.java index 9869a2c..5893c5d 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/table/HAlign.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/table/HAlign.java @@ -62,9 +62,9 @@ public enum HAlign { /** * Calculate text position. * - * @param text Text - * @param colWidth - * @return + * @param text the text to align. + * @param colWidth the column width. + * @return the string at the given position. */ public abstract String position(String text, int colWidth); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/core/src/main/java/org/apache/karaf/shell/support/table/ShellTable.java ---------------------------------------------------------------------- diff --git a/shell/core/src/main/java/org/apache/karaf/shell/support/table/ShellTable.java b/shell/core/src/main/java/org/apache/karaf/shell/support/table/ShellTable.java index 2cb6899..a5f0f02 100644 --- a/shell/core/src/main/java/org/apache/karaf/shell/support/table/ShellTable.java +++ b/shell/core/src/main/java/org/apache/karaf/shell/support/table/ShellTable.java @@ -67,9 +67,10 @@ public class ShellTable { } /** - * Set text to display if there are no rows in the table - * @param text - * @return + * Set text to display if there are no rows in the table. + * + * @param text the text to display when the table is empty. + * @return the shell table. */ public ShellTable emptyTableText(String text) { this.emptyTableText = text; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/ssh/src/main/java/org/apache/karaf/shell/ssh/UserAuthFactoriesFactory.java ---------------------------------------------------------------------- diff --git a/shell/ssh/src/main/java/org/apache/karaf/shell/ssh/UserAuthFactoriesFactory.java b/shell/ssh/src/main/java/org/apache/karaf/shell/ssh/UserAuthFactoriesFactory.java index a7bd297..b31ab93 100644 --- a/shell/ssh/src/main/java/org/apache/karaf/shell/ssh/UserAuthFactoriesFactory.java +++ b/shell/ssh/src/main/java/org/apache/karaf/shell/ssh/UserAuthFactoriesFactory.java @@ -37,12 +37,9 @@ import java.util.Set; * * <p>Currently, the following methods are supported:</p> * <ul> - * <li><code>password</code> - * Password authentication against a given JAAS domain.</p></li> - * <li><code>publickey</code> - * Public key authentication against an OpenSSH <code>authorized_keys</code> file.</p></li> + * <li><code>password</code> Password authentication against a given JAAS domain.</li> + * <li><code>publickey</code> Public key authentication against an OpenSSH <code>authorized_keys</code> file.</li> * </ul> - * </p> */ public class UserAuthFactoriesFactory { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/table/src/main/java/org/apache/karaf/shell/table/HAlign.java ---------------------------------------------------------------------- diff --git a/shell/table/src/main/java/org/apache/karaf/shell/table/HAlign.java b/shell/table/src/main/java/org/apache/karaf/shell/table/HAlign.java index 032d745..b47a186 100644 --- a/shell/table/src/main/java/org/apache/karaf/shell/table/HAlign.java +++ b/shell/table/src/main/java/org/apache/karaf/shell/table/HAlign.java @@ -61,9 +61,9 @@ public enum HAlign { /** * Calculate text position. * - * @param text Text - * @param colWidth - * @return + * @param text The text to align. + * @param colWidth The width of the column. + * @return The aligned string. */ public abstract String position(String text, int colWidth); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/shell/table/src/main/java/org/apache/karaf/shell/table/ShellTable.java ---------------------------------------------------------------------- diff --git a/shell/table/src/main/java/org/apache/karaf/shell/table/ShellTable.java b/shell/table/src/main/java/org/apache/karaf/shell/table/ShellTable.java index e9e936a..955e70a 100644 --- a/shell/table/src/main/java/org/apache/karaf/shell/table/ShellTable.java +++ b/shell/table/src/main/java/org/apache/karaf/shell/table/ShellTable.java @@ -67,9 +67,10 @@ public class ShellTable { } /** - * Set text to display if there are no rows in the table - * @param text - * @return + * Set text to display if there are no rows in the table. + * + * @param text The text to display when the table is empty. + * @return The shell table. */ public ShellTable emptyTableText(String text) { this.emptyTableText = text; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/system/src/main/java/org/apache/karaf/system/SystemService.java ---------------------------------------------------------------------- diff --git a/system/src/main/java/org/apache/karaf/system/SystemService.java b/system/src/main/java/org/apache/karaf/system/SystemService.java index 2f53946..ce4d9ef 100644 --- a/system/src/main/java/org/apache/karaf/system/SystemService.java +++ b/system/src/main/java/org/apache/karaf/system/SystemService.java @@ -35,96 +35,106 @@ public interface SystemService { /** * Halt the Karaf container. + * + * @throws Exception If the halt fails. */ void halt() throws Exception; /** * Halt the Karaf container. * - * @param time shutdown delay. The time argument can have different formats. + * @param time Shutdown delay. The time argument can have different formats. * First, it can be an absolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm * is the minute of the hour (in two digits). Second, it can be in the format +m, in which m is the number of minutes * to wait. The word now is an alias for +0. + * @throws Exception If the halt fails. */ void halt(String time) throws Exception; /** * Reboot the Karaf container. * - * @throws Exception + * @throws Exception If the reboot fails. */ void reboot() throws Exception; /** * Reboot the Karaf container. * - * @param time reboot delay. The time argument can have different formats. + * @param time The reboot delay. The time argument can have different formats. * First, it can be an absolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm * is the minute of the hour (in two digits). Second, it can be in the format +m, in which m is the number of minutes * to wait. The word now is an alias for +0. - * @param clean Force a clean restart by deleting the working directory. + * @param clean Force a clean restart by deleting the working directory. + * @throws Exception If the reboot fails. */ void reboot(String time, Swipe clean) throws Exception; /** * Set the system start level. * - * @param startLevel the new system start level. + * @param startLevel The new system start level. + * @throws Exception If setting the start level fails. */ void setStartLevel(int startLevel) throws Exception; /** * Get the system start level. * - * @return the current system start level. + * @return The current system start level. + * @throws Exception If an error occurs while retrieving the start level. */ int getStartLevel() throws Exception; /** - * Get the version of the current Karaf instance + * Get the version of the current Karaf instance. * - * @return instance version + * @return The instance version. */ String getVersion(); /** - * Get the name of the current Karaf instance + * Get the name of the current Karaf instance. * - * @return instance name + * @return The instance name. */ String getName(); /** - * Set the name of the Karaf instance + * Set the name of the Karaf instance. * - * @param name new instance name + * @param name The new instance name. */ void setName(String name); /** * Get the current OSGi framework in use. * - * @return the name of the OSGi framework in use. - * @throws Exception + * @return The {@link FrameworkType} representing the OSGi framework in use. */ FrameworkType getFramework(); /** - * change OSGi framework + * Change OSGi framework to use. * - * @param framework to use. + * @param framework The new OSGi framework to use. */ void setFramework(FrameworkType framework); /** - * Enable or diable debgging - * @param debug enable if true + * Enable or disable debugging. + * + * @param debug True to enable debugging, false else. */ void setFrameworkDebug(boolean debug); /** - * Set a system property and persist to etc/system.properties - * @param key + * Set a system property and persist to etc/system.properties. + * + * @param key The system property key. + * @param value The system property value. + * @param persist True to persist the change in Karaf etc configuration file, false else. + * @return The system property value as set. */ String setSystemProperty(String key, String value, boolean persist); } http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/system/src/main/java/org/apache/karaf/system/management/SystemMBean.java ---------------------------------------------------------------------- diff --git a/system/src/main/java/org/apache/karaf/system/management/SystemMBean.java b/system/src/main/java/org/apache/karaf/system/management/SystemMBean.java index 5d9bdbc..e021ae7 100644 --- a/system/src/main/java/org/apache/karaf/system/management/SystemMBean.java +++ b/system/src/main/java/org/apache/karaf/system/management/SystemMBean.java @@ -25,9 +25,9 @@ import java.util.Map; public interface SystemMBean { /** - * Stop the Karaf instance + * Stop the Karaf instance. * - * @throws Exception + * @throws MBeanException If a failure occurs. */ void halt() throws MBeanException; @@ -35,14 +35,14 @@ public interface SystemMBean { * Stop the Karaf instance at a given time. * * @param time the time when to stop the Karaf instance. - * @throws Exception + * @throws MBeanException If a failure occurs. */ void halt(String time) throws MBeanException; /** * Reboot the Karaf instance. * - * @throws Exception + * @throws MBeanException If a failure occurs. */ void reboot() throws MBeanException; @@ -50,7 +50,7 @@ public interface SystemMBean { * Reboot the Karaf instance at a given time. * * @param time the time when to reboot the Karaf instance. - * @throws Exception + * @throws MBeanException If a failure occurs. */ void reboot(String time) throws MBeanException; @@ -58,7 +58,7 @@ public interface SystemMBean { * Reboot the Karaf instance at a given time and clean the cache. * * @param time the time when to reboot the Karaf instance. - * @throws Exception + * @throws MBeanException If a failure occurs. */ void rebootCleanCache(String time) throws MBeanException; @@ -66,7 +66,7 @@ public interface SystemMBean { * Reboot the Karaf instance at a given time and clean all working files. * * @param time the time when to reboot the Karaf instance. - * @throws Exception + * @throws MBeanException If a failure occurs. */ void rebootCleanAll(String time) throws MBeanException; @@ -74,7 +74,7 @@ public interface SystemMBean { * Set the system bundle start level. * * @param startLevel the new system bundle start level. - * @throws Exception + * @throws MBeanException If a failure occurs. */ void setStartLevel(int startLevel) throws MBeanException; @@ -82,7 +82,7 @@ public interface SystemMBean { * Get the current system bundle start level. * * @return the current system bundle start level. - * @throws Exception + * @throws MBeanException If a failure occurs. */ int getStartLevel() throws MBeanException; @@ -90,19 +90,19 @@ public interface SystemMBean { * Get the current OSGi framework in use. * * @return the name of the OSGi framework in use. - * @throws Exception */ String getFramework(); /** - * change OSGi framework + * Change OSGi framework * - * @param framework to use. + * @param framework The framework to use. */ void setFramework(String framework); /** - * Enable or diable debgging + * Enable or disable debugging + * * @param debug enable if true */ void setFrameworkDebug(boolean debug); @@ -134,6 +134,7 @@ public interface SystemMBean { * @param unset if true, display the OSGi properties even if they are not defined (with "undef" value). * @param dumpToFile if true, dump the properties into a file in the data folder. * @return the list of system properties. + * @throws MBeanException If a failure occurs. */ Map<String, String> getProperties(boolean unset, boolean dumpToFile) throws MBeanException; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/AssemblyMojo.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/AssemblyMojo.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/AssemblyMojo.java index a2dcaa9..46c79dd 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/AssemblyMojo.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/AssemblyMojo.java @@ -51,7 +51,6 @@ import java.util.Map; * from ${project.build.directory}/classes. Thus, a file in src/main/resources/etc * will be copied by the resource plugin to ${project.build.directory}/classes/etc, * and then added to the assembly by this goal. - * <br> */ @Mojo(name = "assembly", defaultPhase = LifecyclePhase.PACKAGE, requiresDependencyResolution = ResolutionScope.RUNTIME, threadSafe = true) public class AssemblyMojo extends MojoSupport { @@ -218,8 +217,8 @@ public class AssemblyMojo extends MojoSupport { </edit> </edits> </property-edits> - </pre> } + </pre> */ @Parameter(defaultValue = "${project.basedir}/src/main/karaf/assembly-property-edits.xml") protected String propertyFileEdits; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java index e5915d5..f7e24ea 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java @@ -27,19 +27,19 @@ import org.apache.karaf.shell.api.action.Action; public interface CommandHelpPrinter { /** - * Print help for a single action to the out stream + * Print help for a single action to the out stream. * - * @param action - * @param out stream to write to - * @param includeHelpOption include the help option in the doc + * @param action The command {@link Action}. + * @param out The stream where to print the help. + * @param includeHelpOption True to include the help option in the doc, false else. */ void printHelp(Action action, PrintStream out, boolean includeHelpOption); /** - * Print the overview of all given commands to the out stream + * Print the overview of all given commands to the out stream. * - * @param commands - * @param out + * @param commands The {@link Map} of commands to consider in the overview. + * @param out The stream where to write the overview. */ void printOverview(Map<String, Set<String>> commands, PrintStream out); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/features/AbstractFeatureMojo.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/features/AbstractFeatureMojo.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/features/AbstractFeatureMojo.java index 93d823d..dda4350 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/features/AbstractFeatureMojo.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/features/AbstractFeatureMojo.java @@ -137,8 +137,8 @@ public abstract class AbstractFeatureMojo extends MojoSupport { * Resolves and copies the given artifact to the repository path. * Prefers to resolve using the repository of the artifact if present. * - * @param artifact - * @param remoteRepos + * @param artifact The artifact. + * @param remoteRepos The {@link List} of remote repositories to use for artifact resolution. */ @SuppressWarnings("deprecation") protected void resolveArtifact(Artifact artifact, List<ArtifactRepository> remoteRepos) { @@ -164,10 +164,10 @@ public abstract class AbstractFeatureMojo extends MojoSupport { * Populate the features by traversing the listed features and their * dependencies if transitive is true * - * @param featureNames - * @param features - * @param featuresMap - * @param transitive + * @param featureNames The {@link List} of feature names. + * @param features The {@link Set} of features. + * @param featuresMap The {@link Map} of features. + * @param transitive True to add transitive features, false else. */ protected void addFeatures(List<String> featureNames, Set<Feature> features, Map<String, Feature> featuresMap, boolean transitive) { for (String feature : featureNames) { @@ -284,7 +284,7 @@ public abstract class AbstractFeatureMojo extends MojoSupport { /** * Maven ArtifactResolver leaves file handles around so need to clean up - * or we will run out of file descriptors + * or we will run out of file descriptors. */ protected void checkDoGarbageCollect() { if (this.resolveCount++ % 100 == 0) { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelper.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelper.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelper.java index ece73c4..e2e3bf7 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelper.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelper.java @@ -54,16 +54,18 @@ public interface DependencyHelper { /** * Convert a Maven <code>Artifact</code> into a PAX URL mvn format. * - * @param artifact the Maven <code>Artifact</code>. - * @return the corresponding PAX URL mvn format (mvn:groupId/artifactId/version/type/classifier) + * @param artifact The Maven <code>Artifact</code>. + * @return The corresponding PAX URL mvn format (mvn:groupId/artifactId/version/type/classifier) + * @throws MojoExecutionException If the plugin execution fails. */ public String artifactToMvn(Artifact artifact) throws MojoExecutionException; /** * Convert an Aether (Sonatype or Eclipse) artifact into a PAX URL mvn format. * - * @param object the Aether <code>org.sonatype|eclipse.aether.artifact.Artifact</code>. - * @return the corresponding PAX URL mvn format (mvn:groupId/artifactId/version/type/classifier) + * @param object The Aether <code>org.sonatype|eclipse.aether.artifact.Artifact</code>. + * @return The corresponding PAX URL mvn format (mvn:groupId/artifactId/version/type/classifier). + * @throws MojoExecutionException If the plugin execution fails. */ public String artifactToMvn(Object object) throws MojoExecutionException; @@ -73,15 +75,17 @@ public interface DependencyHelper { * Convert a PAX URL mvn format into a filesystem path. * * @param name PAX URL mvn format (mvn:groupId/artifactId/version/type/classifier). - * @return a filesystem path. + * @return The filesystem path. + * @throws MojoExecutionException If the plugin execution fails. */ public String pathFromMaven(String name) throws MojoExecutionException; /** * Convert an Aether coordinate format into a filesystem path. * - * @param name the Aether coordinate format (groupId:artifactId[:extension[:classifier]]:version). - * @return the filesystem path. + * @param name The Aether coordinate format (groupId:artifactId[:extension[:classifier]]:version). + * @return The filesystem path. + * @throws MojoExecutionException If the plugin execution fails. */ public String pathFromAether(String name) throws MojoExecutionException; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelperFactory.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelperFactory.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelperFactory.java index f278e7b..e60edf9 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelperFactory.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/DependencyHelperFactory.java @@ -42,12 +42,12 @@ public class DependencyHelperFactory { * * <p>When {@code karaf-maven-plugin} switches to {@code maven-core:3.1.0+}, reflection should be use for Sonatype variant of Aether.</p> * - * @param container - * @param mavenProject - * @param mavenSession - * @param log - * @return - * @throws MojoExecutionException + * @param container The Maven Plexus container to use. + * @param mavenProject The Maven project to use. + * @param mavenSession The Maven session. + * @param log The log to use for the messages. + * @return The {@link DependencyHelper} depending of the Maven version used. + * @throws MojoExecutionException If the plugin execution fails. */ public static DependencyHelper createDependencyHelper(PlexusContainer container, MavenProject mavenProject, MavenSession mavenSession, Log log) throws MojoExecutionException { try { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MavenUtil.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MavenUtil.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MavenUtil.java index f1eb4ec..4d11dd5 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MavenUtil.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MavenUtil.java @@ -49,7 +49,7 @@ public class MavenUtil { * N.B. version is required in mvn urls. * * @param name PAX URL mvn format: mvn-uri := [ 'wrap:' ] 'mvn:' [ repository-url '!' ] group-id '/' artifact-id [ '/' [version] [ '/' [type] [ '/' classifier ] ] ] ] - * @return aether coordinate format: <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version> + * @return aether coordinate format: <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version> */ public static String mvnToAether(String name) { Matcher m = mvnPattern.matcher(name); @@ -86,7 +86,7 @@ public class MavenUtil { * N.B. we do not handle repository-url in mvn urls. * N.B. version is required in mvn urls. * - * @param name aether coordinate format: <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version> + * @param name aether coordinate format: <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version> * @return PAX URL mvn format: mvn-uri := 'mvn:' [ repository-url '!' ] group-id '/' artifact-id [ '/' [version] [ '/' [type] [ '/' classifier ] ] ] ] */ public static String aetherToMvn(String name) { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MojoSupport.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MojoSupport.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MojoSupport.java index 24a5fef..9910140 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MojoSupport.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/utils/MojoSupport.java @@ -212,7 +212,9 @@ public abstract class MojoSupport extends AbstractMojo { } /** - * Required because Maven 3 returns null in {@link ArtifactRepository#getProtocol()} (see KARAF-244) + * Required because Maven 3 returns null in {@link ArtifactRepository#getProtocol()} (see KARAF-244). + * + * @return The protocol extracted from the local Maven repository URL. */ private String extractProtocolFromLocalMavenRepo() { try { @@ -237,10 +239,10 @@ public abstract class MojoSupport extends AbstractMojo { /** * Convert a feature resourceLocation (bundle or configuration file) into an artifact. * - * @param resourceLocation the feature resource location (bundle or configuration file). - * @param skipNonMavenProtocols flag to skip protocol different than mvn: - * @return the artifact corresponding to the resource. - * @throws MojoExecutionException + * @param resourceLocation The feature resource location (bundle or configuration file). + * @param skipNonMavenProtocols A flag to skip protocol different than mvn: + * @return The artifact corresponding to the resource. + * @throws MojoExecutionException If the plugin execution fails. */ protected Artifact resourceToArtifact(String resourceLocation, boolean skipNonMavenProtocols) throws MojoExecutionException { resourceLocation = resourceLocation.replace("\r\n", "").replace("\n", "").replace(" ", "").replace("\t", ""); @@ -363,10 +365,10 @@ public abstract class MojoSupport extends AbstractMojo { /** - * Make sure the target directory exists and - * that is actually a directory - * @param targetDir - * @throws IOException + * Make sure the target directory exists and that is actually a directory. + * + * @param targetDir The target directory. + * @throws IOException If the target directory is not actually a directory or can't be created. */ private static void ensureDirExists(File targetDir) { if (!targetDir.exists()) { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/StringEscapeUtils.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/StringEscapeUtils.java b/util/src/main/java/org/apache/karaf/util/StringEscapeUtils.java index ac0c984..f632a57 100644 --- a/util/src/main/java/org/apache/karaf/util/StringEscapeUtils.java +++ b/util/src/main/java/org/apache/karaf/util/StringEscapeUtils.java @@ -134,12 +134,11 @@ public class StringEscapeUtils { * <p>The only difference between Java strings and JavaScript strings * is that in JavaScript, a single quote must be escaped.</p> * - * <p>Example: + * Example: * <pre> * input string: He didn't say, "Stop!" * output string: He didn't say, \"Stop!\" * </pre> - * </p> * * @param str String to escape values in, may be null * @return String with escaped values, <code>null</code> if null string input http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/collections/CopyOnWriteArrayIdentityList.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/collections/CopyOnWriteArrayIdentityList.java b/util/src/main/java/org/apache/karaf/util/collections/CopyOnWriteArrayIdentityList.java index 9b34352..d9daa86 100644 --- a/util/src/main/java/org/apache/karaf/util/collections/CopyOnWriteArrayIdentityList.java +++ b/util/src/main/java/org/apache/karaf/util/collections/CopyOnWriteArrayIdentityList.java @@ -1151,6 +1151,7 @@ public class CopyOnWriteArrayIdentityList<E> implements List<E>, RandomAccess, C * * @param ois ObjectInputStream to read object from. * @throws IOException if an I/O error occur. + * @throws ClassNotFoundException If the object class is not found. */ private void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/config/PropertiesLoader.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/config/PropertiesLoader.java b/util/src/main/java/org/apache/karaf/util/config/PropertiesLoader.java index 609957b..cf9a201 100644 --- a/util/src/main/java/org/apache/karaf/util/config/PropertiesLoader.java +++ b/util/src/main/java/org/apache/karaf/util/config/PropertiesLoader.java @@ -50,12 +50,13 @@ public class PropertiesLoader { * The installation directory of Felix is assumed to be the parent * directory of the <tt>felix.jar</tt> file as found on the system class * path property. The precise file from which to load configuration - * properties can be set by initializing the "<tt>felix.config.properties</tt>" + * properties can be set by initializing the "<code>felix.config.properties</code>" * system property to an arbitrary URL. * </p> * - * @return A <tt>Properties</tt> instance or <tt>null</tt> if there was an error. - * @throws Exception if something wrong occurs + * @param file the config file where to load the properties. + * @return A <code>Properties</code> instance or <code>null</code> if there was an error. + * @throws Exception if something wrong occurs. */ public static Properties loadConfigProperties(File file) throws Exception { // See if the property URL was specified as a property. @@ -96,8 +97,8 @@ public class PropertiesLoader { * arbitrary URL. * </p> * - * @param karafBase the karaf base folder - * @throws IOException + * @param file the Karaf base folder. + * @throws IOException if the system file can't be loaded. */ public static void loadSystemProperties(File file) throws IOException { Properties props = new Properties(false); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/maven/Parser.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/maven/Parser.java b/util/src/main/java/org/apache/karaf/util/maven/Parser.java index 23644c7..289c238 100644 --- a/util/src/main/java/org/apache/karaf/util/maven/Parser.java +++ b/util/src/main/java/org/apache/karaf/util/maven/Parser.java @@ -22,7 +22,7 @@ import java.net.MalformedURLException; import java.util.Map; /** - * Parser for mvn: protocol.<br/> + * Parser for mvn: protocol. * * @author Alin Dreghiciu * @author Toni Menzel @@ -122,7 +122,6 @@ public class Parser * Creates a new protocol parser. * * @param path the path part of the url (without starting mvn:) - * * @throws MalformedURLException if provided path does not comply to expected syntax or an malformed repository URL */ public Parser( final String path ) @@ -151,10 +150,10 @@ public class Parser } /** - * Returns the artifact path from the given maven uri. - * @param uri the maven uri - * @return the artifact path - * @throws MalformedURLException + * Return the artifact path from the given maven uri. + * @param uri the Maven URI. + * @return the artifact actual path. + * @throws MalformedURLException in case of "bad" provided URL/URI. */ public static String pathFromMaven(String uri) throws MalformedURLException { if (!uri.startsWith("mvn:")) { @@ -211,10 +210,9 @@ public class Parser } /** - * Parses the artifact part of the url ( without the repository). + * Parse the artifact part of the url (without the repository). * * @param part url part without protocol and repository. - * * @throws MalformedURLException if provided path does not comply to syntax. */ private void parseArtifactPart( final String part ) @@ -259,9 +257,9 @@ public class Parser } /** - * Returns the repository URL if present, null otherwise + * Return the repository URL if present, null otherwise. * - * @return repository URL + * @return repository URL. */ public String getRepositoryURL() { @@ -269,9 +267,9 @@ public class Parser } /** - * Returns the group id of the artifact. + * Return the group id of the artifact. * - * @return group Id + * @return group ID. */ public String getGroup() { @@ -279,9 +277,9 @@ public class Parser } /** - * Returns the artifact id. + * Return the artifact id. * - * @return artifact id + * @return artifact id. */ public String getArtifact() { @@ -289,9 +287,9 @@ public class Parser } /** - * Returns the artifact version. + * Return the artifact version. * - * @return version + * @return version. */ public String getVersion() { @@ -299,9 +297,9 @@ public class Parser } /** - * Returns the artifact type. + * Return the artifact type. * - * @return type + * @return type. */ public String getType() { @@ -309,9 +307,9 @@ public class Parser } /** - * Returns the artifact classifier. + * Return the artifact classifier. * - * @return classifier + * @return classifier. */ public String getClassifier() { @@ -319,9 +317,9 @@ public class Parser } /** - * Returns the complete path to artifact as stated by Maven 2 repository layout. + * Return the complete path to artifact as stated by Maven 2 repository layout. * - * @return artifact path + * @return artifact path. */ public String getArtifactPath() { @@ -329,11 +327,10 @@ public class Parser } /** - * Returns the complete path to artifact as stated by Maven 2 repository layout. + * Return the complete path to artifact as stated by Maven 2 repository layout. * * @param version The version of the artifact. - * - * @return artifact path + * @return artifact path. */ public String getArtifactPath( final String version ) { @@ -354,13 +351,12 @@ public class Parser } /** - * Returns the version for an artifact for a snapshot version. + * Return the version for an artifact for a snapshot version. * - * @param version The version of the snapshot. - * @param timestamp The timestamp of the snapshot. + * @param version The version of the snapshot. + * @param timestamp The timestamp of the snapshot. * @param buildnumber The buildnumber of the snapshot. - * - * @return artifact path + * @return artifact path. */ public String getSnapshotVersion( final String version, final String timestamp, final String buildnumber ) { @@ -368,13 +364,12 @@ public class Parser } /** - * Returns the complete path to artifact for a snapshot file. + * Return the complete path to artifact for a snapshot file. * - * @param version The version of the snapshot. - * @param timestamp The timestamp of the snapshot. + * @param version The version of the snapshot. + * @param timestamp The timestamp of the snapshot. * @param buildnumber The buildnumber of the snapshot. - * - * @return artifact path + * @return artifact path. */ public String getSnapshotPath( final String version, final String timestamp, final String buildnumber ) { @@ -395,11 +390,10 @@ public class Parser } /** - * Returns the path to metdata file corresponding to this artifact version. + * Return the path to metadata file corresponding to this artifact version. * * @param version The version of the the metadata. - * - * @return metadata file path + * @return metadata file path. */ public String getVersionMetadataPath( final String version ) { @@ -415,11 +409,10 @@ public class Parser } /** - * Returns the path to local metdata file corresponding to this artifact version. + * Return the path to local metadata file corresponding to this artifact version. * * @param version The version of the the metadata. - * - * @return metadata file path + * @return metadata file path. */ public String getVersionLocalMetadataPath( final String version ) { @@ -435,9 +428,9 @@ public class Parser } /** - * Returns the complete path to artifact local metadata file. + * Return the complete path to artifact local metadata file. * - * @return artifact path + * @return artifact path. */ public String getArtifactLocalMetdataPath() { @@ -451,9 +444,9 @@ public class Parser } /** - * Returns the complete path to artifact metadata file. + * Return the complete path to artifact metadata file. * - * @return artifact path + * @return artifact path. */ public String getArtifactMetdataPath() { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/process/PumpStreamHandler.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/process/PumpStreamHandler.java b/util/src/main/java/org/apache/karaf/util/process/PumpStreamHandler.java index 76d09e6..6e2eeb2 100644 --- a/util/src/main/java/org/apache/karaf/util/process/PumpStreamHandler.java +++ b/util/src/main/java/org/apache/karaf/util/process/PumpStreamHandler.java @@ -16,7 +16,6 @@ * specific language governing permissions and limitations * under the License. */ - package org.apache.karaf.util.process; import java.io.InputStream; @@ -26,8 +25,8 @@ import java.io.IOException; /** * Copies standard output and error of children streams to standard output and error of the parent. */ -public class PumpStreamHandler -{ +public class PumpStreamHandler { + private final InputStream in; private final OutputStream out; @@ -72,6 +71,8 @@ public class PumpStreamHandler /** * Set the input stream from which to read the standard output of the child. + * + * @param in the the child output stream. */ public void setChildOutputStream(final InputStream in) { assert in != null; @@ -81,6 +82,8 @@ public class PumpStreamHandler /** * Set the input stream from which to read the standard error of the child. + * + * @param in set the child error stream. */ public void setChildErrorStream(final InputStream in) { assert in != null; @@ -92,6 +95,8 @@ public class PumpStreamHandler /** * Set the output stream by means of which input can be sent to the child. + * + * @param out set the child output stream. */ public void setChildInputStream(final OutputStream out) { assert out != null; @@ -109,7 +114,7 @@ public class PumpStreamHandler /** * Attach to a child streams from the given process. * - * @param p The process to attach to. + * @param p The process to attach to. */ public void attach(final Process p) { assert p != null; @@ -118,6 +123,7 @@ public class PumpStreamHandler setChildOutputStream(p.getInputStream()); setChildErrorStream(p.getErrorStream()); } + /** * Start pumping the streams. */ @@ -191,6 +197,9 @@ public class PumpStreamHandler /** * Create the pump to handle child output. + * + * @param in the child input stream. + * @param out the child output stream. */ protected void createChildOutputPump(final InputStream in, final OutputStream out) { assert in != null; @@ -201,6 +210,9 @@ public class PumpStreamHandler /** * Create the pump to handle error output. + * + * @param in the child input stream. + * @param out the child output stream. */ protected void createChildErrorPump(final InputStream in, final OutputStream out) { assert in != null; @@ -210,7 +222,11 @@ public class PumpStreamHandler } /** - * Creates a stream pumper to copy the given input stream to the given output stream. + * Create a stream pumper to copy the given input stream to the given output stream. + * + * @param in the child input stream. + * @param out the child output stream. + * @return A thread object that does the pumping. */ protected StreamPumper createPump(final InputStream in, final OutputStream out) { assert in != null; @@ -220,13 +236,13 @@ public class PumpStreamHandler } /** - * Creates a stream pumper to copy the given input stream to the + * Create a stream pumper to copy the given input stream to the * given output stream. * - * @param in The input stream to copy from. - * @param out The output stream to copy to. - * @param closeWhenExhausted If true close the inputstream. - * @return A thread object that does the pumping. + * @param in The input stream to copy from. + * @param out The output stream to copy to. + * @param closeWhenExhausted If true close the input stream. + * @return A thread object that does the pumping. */ protected StreamPumper createPump(final InputStream in, final OutputStream out, final boolean closeWhenExhausted) { assert in != null; @@ -237,8 +253,13 @@ public class PumpStreamHandler } /** - * Creates a stream pumper to copy the given input stream to the + * Create a stream pumper to copy the given input stream to the * given output stream. Used for standard input. + * + * @param in The input stream to copy from. + * @param out The output stream to copy to. + * @param closeWhenExhausted If true close the input stream. + * @return A thread object that does the pumping. */ protected StreamPumper createInputPump(final InputStream in, final OutputStream out, final boolean closeWhenExhausted) { assert in != null; @@ -257,4 +278,5 @@ public class PumpStreamHandler public StreamPumper getErrorPump() { return this.errorPump; } + } http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/process/StreamPumper.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/process/StreamPumper.java b/util/src/main/java/org/apache/karaf/util/process/StreamPumper.java index b49cdae..3001442 100644 --- a/util/src/main/java/org/apache/karaf/util/process/StreamPumper.java +++ b/util/src/main/java/org/apache/karaf/util/process/StreamPumper.java @@ -16,7 +16,6 @@ * specific language governing permissions and limitations * under the License. */ - package org.apache.karaf.util.process; import java.io.InputStream; @@ -26,8 +25,8 @@ import java.io.IOException; /** * Copies all data from an input stream to an output stream. */ -public class StreamPumper implements Runnable -{ +public class StreamPumper implements Runnable { + private InputStream in; private OutputStream out; @@ -53,10 +52,9 @@ public class StreamPumper implements Runnable /** * Create a new stream pumper. * - * @param in Input stream to read data from - * @param out Output stream to write data to. - * @param closeWhenExhausted If true, the output stream will be closed when - * the input is exhausted. + * @param in The input stream to read data from. + * @param out The output stream to write data to. + * @param closeWhenExhausted If true, the output stream will be closed when the input is exhausted. */ public StreamPumper(final InputStream in, final OutputStream out, final boolean closeWhenExhausted) { assert in != null; @@ -70,8 +68,8 @@ public class StreamPumper implements Runnable /** * Create a new stream pumper. * - * @param in Input stream to read data from - * @param out Output stream to write data to. + * @param in The input stream to read data from. + * @param out The output stream to write data to. */ public StreamPumper(final InputStream in, final OutputStream out) { this(in, out, false); @@ -88,7 +86,7 @@ public class StreamPumper implements Runnable /** * Set whether data should be flushed through to the output stream. * - * @param autoflush If true, push through data; if false, let it be buffered + * @param autoflush If true, push through data; if false, let it be buffered. */ public void setAutoflush(boolean autoflush) { this.autoflush = autoflush; @@ -96,16 +94,17 @@ public class StreamPumper implements Runnable /** * Set whether data should be read in a non blocking way. - * @param nonBlocking If true, data will be read in a non blocking mode + * + * @param nonBlocking If true, data will be read in a non blocking mode. */ public void setNonBlocking(boolean nonBlocking) { this.nonBlocking = nonBlocking; } /** - * Copies data from the input stream to the output stream. + * Copy data from the input stream to the output stream. * - * Terminates as soon as the input stream is closed or an error occurs. + * Terminate as soon as the input stream is closed or an error occurs. */ public void run() { synchronized (this) { @@ -175,9 +174,9 @@ public class StreamPumper implements Runnable } /** - * Tells whether the end of the stream has been reached. + * Tell whether the end of the stream has been reached. * - * @return true If the stream has been exhausted. + * @return true if the stream has been exhausted. */ public synchronized boolean isFinished() { return finished; @@ -187,6 +186,7 @@ public class StreamPumper implements Runnable * This method blocks until the stream pumper finishes. * * @see #isFinished() + * @throws InterruptedException if the stream pumper has been interrupted. */ public synchronized void waitFor() throws InterruptedException { while (!isFinished()) { @@ -198,7 +198,6 @@ public class StreamPumper implements Runnable * Set the size in bytes of the read buffer. * * @param bufferSize the buffer size to use. - * @throws IllegalStateException if the StreamPumper is already running. */ public synchronized void setBufferSize(final int bufferSize) { if (started) { http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/tracker/BaseActivator.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/tracker/BaseActivator.java b/util/src/main/java/org/apache/karaf/util/tracker/BaseActivator.java index e3e39d4..a1e8a6d 100644 --- a/util/src/main/java/org/apache/karaf/util/tracker/BaseActivator.java +++ b/util/src/main/java/org/apache/karaf/util/tracker/BaseActivator.java @@ -129,7 +129,9 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doOpen()} + * Called in {@link #doOpen()}. + * + * @param pid The configuration PID to manage (ManagedService). */ protected void manage(String pid) { Hashtable<String, Object> props = new Hashtable<>(); @@ -146,8 +148,13 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing protected Dictionary<String, ?> getConfiguration() { return configuration; } + /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param key The configuration key + * @param def The default value. + * @return The value of the configuration key if found, the default value else. */ protected int getInt(String key, int def) { if (configuration != null) { @@ -162,7 +169,11 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param key The configuration key. + * @param def The default value. + * @return The value of the configuration key if found, the default value else. */ protected boolean getBoolean(String key, boolean def) { if (configuration != null) { @@ -177,7 +188,11 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param key The configuration key. + * @param def The default value. + * @return The value of the configuration key if found, the default value else. */ protected long getLong(String key, long def) { if (configuration != null) { @@ -192,7 +207,11 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param key The configuration key. + * @param def The default value. + * @return The value of the configuration key if found, the default value else. */ protected String getString(String key, String def) { if (configuration != null) { @@ -238,7 +257,10 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doOpen()} + * Called in {@link #doOpen()}. + * + * @param clazz The service interface to track. + * @throws InvalidSyntaxException If the tracker syntax is not correct. */ protected void trackService(Class<?> clazz) throws InvalidSyntaxException { if (!trackers.containsKey(clazz.getName())) { @@ -249,7 +271,11 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doOpen()} + * Called in {@link #doOpen()}. + * + * @param clazz The service interface to track. + * @param filter The filter to use to select the services to track. + * @throws InvalidSyntaxException If the tracker syntax is not correct (in the filter especially). */ protected void trackService(Class<?> clazz, String filter) throws InvalidSyntaxException { if (!trackers.containsKey(clazz.getName())) { @@ -271,7 +297,11 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param clazz The service interface to get. + * @param <T> The service type. + * @return The actual tracker service object. */ protected <T> T getTrackedService(Class<T> clazz) { SingleServiceTracker tracker = trackers.get(clazz.getName()); @@ -282,7 +312,10 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param mbean The MBean to register. + * @param type The MBean type to register. */ protected void registerMBean(Object mbean, String type) { Hashtable<String, Object> props = new Hashtable<>(); @@ -291,28 +324,44 @@ public class BaseActivator implements BundleActivator, SingleServiceTracker.Sing } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param clazz The service interface to register. + * @param <T> The service type. + * @param service The actual service instance to register. */ protected <T> void register(Class<T> clazz, T service) { register(clazz, service, null); } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param clazz The service interface to register. + * @param <T> The service type. + * @param service The actual service instance to register. + * @param props The service properties to register. */ protected <T> void register(Class<T> clazz, T service, Dictionary<String, ?> props) { trackRegistration(bundleContext.registerService(clazz, service, props)); } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param clazz The service interfaces to register. + * @param service The actual service instance to register. */ protected void register(Class[] clazz, Object service) { register(clazz, service, null); } /** - * Called in {@link #doStart()} + * Called in {@link #doStart()}. + * + * @param clazz The service interfaces to register. + * @param service The actual service instance to register. + * @param props The service properties to register. */ protected void register(Class[] clazz, Object service, Dictionary<String, ?> props) { String[] names = new String[clazz.length]; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/util/src/main/java/org/apache/karaf/util/tracker/SingleServiceTracker.java ---------------------------------------------------------------------- diff --git a/util/src/main/java/org/apache/karaf/util/tracker/SingleServiceTracker.java b/util/src/main/java/org/apache/karaf/util/tracker/SingleServiceTracker.java index 890d44c..d46d829 100644 --- a/util/src/main/java/org/apache/karaf/util/tracker/SingleServiceTracker.java +++ b/util/src/main/java/org/apache/karaf/util/tracker/SingleServiceTracker.java @@ -16,8 +16,6 @@ * specific language governing permissions and limitations * under the License. */ - - package org.apache.karaf.util.tracker; import java.util.Arrays; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/web/src/main/java/org/apache/karaf/web/WebContainerService.java ---------------------------------------------------------------------- diff --git a/web/src/main/java/org/apache/karaf/web/WebContainerService.java b/web/src/main/java/org/apache/karaf/web/WebContainerService.java index 7ec1ee7..791230a 100644 --- a/web/src/main/java/org/apache/karaf/web/WebContainerService.java +++ b/web/src/main/java/org/apache/karaf/web/WebContainerService.java @@ -57,10 +57,10 @@ public interface WebContainerService { void stop(List<Long> bundleIds) throws Exception; /** - * Retrieves the Web-ContextPath of the corresponding bundle + * Retrieve the Web-ContextPath of the corresponding bundle. * - * @param id of the bundle. - * @return + * @param id The ID of the bundle. + * @return The web context associated with the given bundle. */ String getWebContextPath(Long id); http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/web/src/main/java/org/apache/karaf/web/management/WebMBean.java ---------------------------------------------------------------------- diff --git a/web/src/main/java/org/apache/karaf/web/management/WebMBean.java b/web/src/main/java/org/apache/karaf/web/management/WebMBean.java index 5c6df22..b9a0b5c 100644 --- a/web/src/main/java/org/apache/karaf/web/management/WebMBean.java +++ b/web/src/main/java/org/apache/karaf/web/management/WebMBean.java @@ -29,7 +29,7 @@ public interface WebMBean { * Return the list of web bundles. * * @return a tabular data of web bundles. - * @throws Exception in case of lookup failure. + * @throws MBeanException in case of lookup failure. */ TabularData getWebBundles() throws MBeanException; @@ -37,7 +37,7 @@ public interface WebMBean { * Start web context of the given web bundle (identified by ID). * * @param bundleId the bundle ID. - * @throws MBeanException + * @throws MBeanException in case of start failure. */ void start(Long bundleId) throws MBeanException; @@ -46,7 +46,7 @@ public interface WebMBean { * * @param bundleIds the list of bundle IDs. * TODO use a BundleSelector service - * @throws Exception in case of start failure. + * @throws MBeanException in case of start failure. */ void start(List<Long> bundleIds) throws MBeanException; @@ -54,7 +54,7 @@ public interface WebMBean { * Stop web context of the given web bundle (identified by ID). * * @param bundleId the bundle ID. - * @throws MBeanException + * @throws MBeanException in case of stop failure. */ void stop(Long bundleId) throws MBeanException; @@ -63,7 +63,7 @@ public interface WebMBean { * * @param bundleIds the list of bundle IDs. * TODO use a BundleSelector service - * @throws Exception in case of stop failure + * @throws MBeanException in case of stop failure */ void stop(List<Long> bundleIds) throws MBeanException; http://git-wip-us.apache.org/repos/asf/karaf/blob/8a1e7574/wrapper/src/main/java/org/apache/karaf/wrapper/WrapperService.java ---------------------------------------------------------------------- diff --git a/wrapper/src/main/java/org/apache/karaf/wrapper/WrapperService.java b/wrapper/src/main/java/org/apache/karaf/wrapper/WrapperService.java index 78a0877..814e9a2 100644 --- a/wrapper/src/main/java/org/apache/karaf/wrapper/WrapperService.java +++ b/wrapper/src/main/java/org/apache/karaf/wrapper/WrapperService.java @@ -25,6 +25,8 @@ public interface WrapperService { /** * Install the Karaf container as a system service in the OS. + * + * @throws Exception If the wrapper install fails. */ public void install() throws Exception; @@ -35,7 +37,8 @@ public interface WrapperService { * @param displayName The display name of the service. * @param description The description of the service. * @param startType Mode in which the service is installed. AUTO_START or DEMAND_START. - * @return an array containing the wrapper configuration file (index 0) and the service file (index 1) + * @return An array containing the wrapper configuration file (index 0) and the service file (index 1). + * @throws Exception If the wrapper install fails. */ public File[] install(String name, String displayName, String description, String startType) throws Exception; @@ -48,7 +51,8 @@ public interface WrapperService { * @param startType Mode in which the service is installed. AUTO_START or DEMAND_START. * @param envs The environment variable and values * @param includes The include statement for JSW wrapper conf - * @return an array containing the wrapper configuration file (index 0) and the service file (index 1) + * @return An array containing the wrapper configuration file (index 0) and the service file (index 1). + * @throws Exception If the wrapper install fails. */ public File[] install(String name, String displayName, String description, String startType, String[] envs, String[] includes) throws Exception;
