Author: jdillon
Date: Fri Jun 20 05:32:24 2008
New Revision: 669873
URL: http://svn.apache.org/viewvc?rev=669873&view=rev
Log:
Add javadocs
Modified:
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Command.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandAction.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandCompleter.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandContext.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandDocumenter.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandException.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandFactory.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandInfo.java
geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Variables.java
geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommand.java
geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandCompleter.java
geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandDocumenter.java
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Command.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Command.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Command.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Command.java
Fri Jun 20 05:32:24 2008
@@ -20,7 +20,7 @@
package org.apache.geronimo.gshell.command;
/**
- * ???
+ * Containment for an installed command and its related components.
*
* @version $Rev$ $Date$
*/
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandAction.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandAction.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandAction.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandAction.java
Fri Jun 20 05:32:24 2008
@@ -20,7 +20,7 @@
package org.apache.geronimo.gshell.command;
/**
- * ???
+ * Provides the user-action for a command.
*
* @version $Rev$ $Date$
*/
@@ -29,11 +29,18 @@
Object execute(CommandContext context) throws Exception;
/**
- * ???
+ * Enumeration for the basic return types of a command execution.
*/
enum Result
{
+ /**
+ * The command execution was successful.
+ */
SUCCESS,
+
+ /**
+ * The command exectuion failed.
+ */
FAILURE
}
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandCompleter.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandCompleter.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandCompleter.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandCompleter.java
Fri Jun 20 05:32:24 2008
@@ -19,12 +19,18 @@
package org.apache.geronimo.gshell.command;
+import jline.Completor;
+
/**
- * ???
+ * Provides completion support for a command.
*
* @version $Rev$ $Date$
*/
public interface CommandCompleter
{
- // TODO:
+ //
+ // TODO: Not really sure this is what we want to do, but for now...
+ //
+
+ Completor createCompletor();
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandContext.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandContext.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandContext.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandContext.java
Fri Jun 20 05:32:24 2008
@@ -28,15 +28,31 @@
*/
public interface CommandContext
{
+ /**
+ * Provides access to the arguments to the command.
+ *
+ * @return The command arguments.
+ */
Object[] getArguments();
-
+
+ /**
+ * The Input/Output context for the command.
+ *
+ * @return Command Input/Output context.
+ */
IO getIo();
+ /**
+ * The variables for the command.
+ *
+ * @return Command variables.
+ */
Variables getVariables();
+ /**
+ * Provides details about the runtime configuration of the command.
+ *
+ * @return Command runtime information.
+ */
CommandInfo getInfo();
-
- // CommandModel getModel();
-
- // CommandContainer getContainer();
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandDocumenter.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandDocumenter.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandDocumenter.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandDocumenter.java
Fri Jun 20 05:32:24 2008
@@ -19,12 +19,40 @@
package org.apache.geronimo.gshell.command;
+import java.io.PrintWriter;
+
/**
- * ???
+ * Provides access to a commands documentation.
*
* @version $Rev$ $Date$
*/
public interface CommandDocumenter
{
- // TODO:
+ /**
+ * Get the name of the command as it has been configured in the layout.
+ *
+ * @return The configured name of the command.
+ */
+ String getName();
+
+ /**
+ * Get the terse description of the command.
+ *
+ * @return The configured description of hte command.
+ */
+ String getDescription();
+
+ /**
+ * Render the command-line usage, as expected from <tt>--help</tt>.
+ *
+ * @param out Write the usage to this writer.
+ */
+ void renderUsage(PrintWriter out);
+
+ /**
+ * Render the full command manual.
+ *
+ * @param out Write the manual to this writer.
+ */
+ void renderManual(PrintWriter out);
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandException.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandException.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandException.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandException.java
Fri Jun 20 05:32:24 2008
@@ -20,7 +20,7 @@
package org.apache.geronimo.gshell.command;
/**
- * A command exception.
+ * Thrown to indicate a command failure. When thrown this implies an explicit return of
{Result.FAILURE}.
*
* @version $Rev$ $Date$
*/
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandFactory.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandFactory.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandFactory.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandFactory.java
Fri Jun 20 05:32:24 2008
@@ -20,7 +20,7 @@
package org.apache.geronimo.gshell.command;
/**
- * ???
+ * Provides access to {@link Command} instances.
*
* @version $Rev$ $Date$
*/
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandInfo.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandInfo.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandInfo.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/CommandInfo.java
Fri Jun 20 05:32:24 2008
@@ -20,7 +20,7 @@
package org.apache.geronimo.gshell.command;
/**
- * Details about the command.
+ * Details about the runtime configuraiton of a command.
*
* @version $Rev$ $Date$
*/
@@ -28,18 +28,22 @@
{
/**
* Returns the <em>identifier</em> for the command.
+ *
+ * @return Command identifier.
*/
String getId();
/**
* Returns the name of the command.
+ *
+ * @return Command name.
*/
String getName();
/**
* Returns the alias used to invoke the command if any.
*
- * @return The alias used to invoke the command; null if not aliased.
+ * @return The alias used to invoke the command; null if not aliased.
*/
String getAlias();
@@ -49,6 +53,8 @@
/**
* Returns the full path of the command.
+ *
+ * @return Command path.
*/
String getPath();
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Variables.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Variables.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Variables.java
(original)
+++ geronimo/gshell/trunk/gshell-api/src/main/java/org/apache/geronimo/gshell/command/Variables.java
Fri Jun 20 05:32:24 2008
@@ -28,30 +28,96 @@
*/
public interface Variables
{
+ /**
+ * Set a value of a variable.
+ *
+ * @param name
+ * @param value
+ * @throws ImmutableVariableException
+ */
void set(String name, Object value) throws ImmutableVariableException;
+ /**
+ * Set a value of a variable, optional making the variable immutable.
+ *
+ * @param name
+ * @param value
+ * @param mutable
+ * @throws ImmutableVariableException
+ */
void set(String name, Object value, boolean mutable) throws ImmutableVariableException;
+ /**
+ * Get the value of a variable.
+ *
+ * @param name
+ * @return
+ */
Object get(String name);
+ /**
+ * Get the value of a variable, if not set using the provided default.
+ *
+ * @param name
+ * @param _default
+ * @return
+ */
Object get(String name, Object _default);
+ /**
+ * Check if a variable is mutable.
+ *
+ * @param name
+ * @return
+ */
boolean isMutable(String name);
+ /**
+ * Check if a variable is cloaked. Cloaked variables exist when a variable of the same
name
+ * has been set in the parent and that variable was not immutable.
+ *
+ * @param name
+ * @return
+ */
boolean isCloaked(String name);
+ /**
+ * Unset a variable.
+ *
+ * @param name
+ * @throws ImmutableVariableException
+ */
void unset(String name) throws ImmutableVariableException;
-
+
+ /**
+ * Check for the existance of a variable.
+ *
+ * @param name
+ * @return
+ */
boolean contains(String name);
-
+
+ /**
+ * Get all variable names.
+ *
+ * @return
+ */
Iterator<String> names();
+ /**
+ * Returns the parent variables container.
+ *
+ * @return
+ */
Variables parent();
//
// Exceptions
//
+ /**
+ * Throw to indicate that a variable change was attempted but the variable was not muable.
+ */
class ImmutableVariableException
extends RuntimeException
{
Modified: geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommand.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommand.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommand.java
(original)
+++ geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommand.java
Fri Jun 20 05:32:24 2008
@@ -114,13 +114,14 @@
log.trace("Executing; context={}");
- CommandAction action = getAction();
-
+ // Provide logging context for the command execution
MDC.put("commandId", commandId);
Object result;
try {
+ CommandAction action = getAction();
+
// Process command line options/arguments, return if we have been asked to display
--help
if (processArguments(context, action, context.getArguments())) {
return CommandAction.Result.SUCCESS;
Modified: geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandCompleter.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandCompleter.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandCompleter.java
(original)
+++ geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandCompleter.java
Fri Jun 20 05:32:24 2008
@@ -25,6 +25,7 @@
import org.codehaus.plexus.component.annotations.Configuration;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+import jline.Completor;
/**
* The default {@link org.apache.geronimo.gshell.command.CommandCompleter} component.
@@ -37,6 +38,12 @@
{
private final Logger log = LoggerFactory.getLogger(getClass());
- @Configuration("") // Just to mark what this is used for, since we have to configure
a default value
+ @Configuration("")
private String commandId;
+
+ public Completor createCompletor() {
+ // TODO:
+
+ throw new Error();
+ }
}
\ No newline at end of file
Modified: geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandDocumenter.java
URL: http://svn.apache.org/viewvc/geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandDocumenter.java?rev=669873&r1=669872&r2=669873&view=diff
==============================================================================
--- geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandDocumenter.java
(original)
+++ geronimo/gshell/trunk/gshell-rapture/src/main/java/org/apache/geronimo/gshell/rapture/DefaultCommandDocumenter.java
Fri Jun 20 05:32:24 2008
@@ -25,6 +25,8 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+import java.io.PrintWriter;
+
/**
* The default {@link org.apache.geronimo.gshell.command.CommandDocumenter} component.
*
@@ -38,4 +40,24 @@
@Configuration("") // Just to mark what this is used for, since we have to configure
a default value
private String commandId;
+
+ public String getName() {
+ return null;
+ }
+
+ public String getDescription() {
+ return null;
+ }
+
+ public void renderUsage(final PrintWriter out) {
+ assert out != null;
+
+ // TODO:
+ }
+
+ public void renderManual(final PrintWriter out) {
+ assert out != null;
+
+ // TODO:
+ }
}
\ No newline at end of file
|