| // *************************************************************************************************************************** |
| // * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * |
| // * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * |
| // * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * |
| // * with the License. You may obtain a copy of the License at * |
| // * * |
| // * http://www.apache.org/licenses/LICENSE-2.0 * |
| // * * |
| // * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * |
| // * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * |
| // * specific language governing permissions and limitations under the License. * |
| // *************************************************************************************************************************** |
| package org.apache.juneau.microservice.console; |
| |
| import java.io.*; |
| import java.util.*; |
| |
| import org.apache.juneau.microservice.*; |
| import org.apache.juneau.utils.*; |
| |
| /** |
| * Implements a command that can be invoked from the console of the microservice. |
| * |
| * <p> |
| * Console commands allow you to interact with your microservice through the system console. |
| * |
| * <p> |
| * Console commands are associated with the microservice through the following: |
| * <ul> |
| * <li>The <js>"Console/commands"</js> configuration value. |
| * <br>This is a comma-delimited list of fully-qualified names of classes implementing this interface. |
| * <br>When associated this way, the implementation class must have a no-arg constructor. |
| * <li>Specifying commands via the {@link MicroserviceBuilder#consoleCommands(Class...)} method. |
| * <br>This allows you to override the default implementation above and augment or replace the list |
| * with your own implementation objects. |
| * </ul> |
| * |
| * <p> |
| * For example, the {@link HelpCommand} is used to provide help on other commands. |
| * |
| * <p class='bcode w800'> |
| * Running class 'JettyMicroservice' using config file 'examples.cfg'. |
| * Server started on port 10000 |
| * |
| * List of available commands: |
| * exit -- Shut down service |
| * restart -- Restarts service |
| * help -- Commands help |
| * echo -- Echo command |
| * |
| * > <span style='color:green'>help help</span> |
| * NAME |
| * help -- Commands help |
| * |
| * SYNOPSIS |
| * help [command] |
| * |
| * DESCRIPTION |
| * When called without arguments, prints the descriptions of all available commands. |
| * Can also be called with one or more arguments to get detailed information on a command. |
| * |
| * EXAMPLES |
| * List all commands: |
| * > help |
| * |
| * List help on the help command: |
| * > help help |
| * |
| * > |
| * </p> |
| * |
| * <p> |
| * The arguments are available as an {@link Args} object which allows for easy accessed to parsed command lines. |
| * Some simple examples of valid command lines: |
| * |
| * <p class='bcode w800'> |
| * <jc>// mycommand</jc> |
| * args.get("0"); <jc>// "mycommand"</jc> |
| * |
| * <jc>// mycommand arg1 arg2</jc> |
| * args.get("0"); <jc>// "mycommand"</jc> |
| * args.get("1"); <jc>// "arg1"</jc> |
| * args.get("2"); <jc>// "arg2"</jc> |
| * |
| * <jc>// mycommand -optArg1 foo bar -optArg2 baz qux</jc> |
| * args.get("0"); <jc>// "mycommand"</jc> |
| * args.get("optArg1", String[].class); <jc>// ["foo","bar"]</jc> |
| * args.get("optArg2", String[].class); <jc>// ["baz","qux"]</jc> |
| * |
| * <jc>// mycommand -optArg1 "foo bar" -optArg2 'baz qux'</jc> |
| * args.get("0"); <jc>// "mycommand"</jc> |
| * args.get("optArg1", String[].class); <jc>// ["foo bar"]</jc> |
| * args.get("optArg2", String[].class); <jc>// ["baz qux"]</jc> |
| * </p> |
| */ |
| public abstract class ConsoleCommand { |
| |
| /** |
| * Returns the name of the command. |
| * |
| * <p> |
| * Example: <js>"help"</js> for the help command. |
| * |
| * @return |
| * The name of the command. |
| * <br>Must not be <jk>null</jk> or contain spaces. |
| */ |
| abstract public String getName(); |
| |
| /** |
| * Returns the usage synopsis of the command. |
| * |
| * <p> |
| * Example: <js>"help [command ...]" |
| * |
| * <p> |
| * The default implementation just returns the name, which implies the command takes no additional arguments. |
| * |
| * @return The synopsis of the command. |
| */ |
| public String getSynopsis() { |
| return getName(); |
| } |
| |
| /** |
| * Returns a one-line localized description of the command. |
| * |
| * <p> |
| * The locale should be the system locale. |
| * |
| * @return |
| * The localized description of the command. |
| * <br>Can be <jk>null</jk> if there is no information. |
| */ |
| public String getInfo() { |
| return null; |
| } |
| |
| /** |
| * Returns localized details of the command. |
| * |
| * <p> |
| * The locale should be the system locale. |
| * |
| * @return |
| * The localized details of the command. |
| * <br>Can be <jk>null</jk> if there is no additional description. |
| */ |
| public String getDescription() { |
| return null; |
| } |
| |
| /** |
| * Returns localized examples of the command. |
| * |
| * <p> |
| * The locale should be the system locale. |
| * |
| * @return |
| * The localized examples of the command. |
| * <br>Can be <jk>null</jk> if there is no examples. |
| */ |
| public String getExamples() { |
| return null; |
| } |
| |
| /** |
| * Executes a command. |
| * @param in The console reader. |
| * @param out The console writer. |
| * @param args The command arguments. The first argument is always the command itself. |
| * |
| * @return |
| * <jk>true</jk> if the console read thread should exit. |
| * <br>Normally you want to return <jk>true</jk> if your action is causing the microservice to exit or restart. |
| * @throws Exception |
| * Any thrown exception will simply be sent to STDERR. |
| */ |
| abstract public boolean execute(Scanner in, PrintWriter out, Args args) throws Exception; |
| } |