From ea8908c019ad90d84b5620a723dff990d745cd7f Mon Sep 17 00:00:00 2001 From: Eric Bottard Date: Wed, 17 May 2017 12:08:01 +0200 Subject: [PATCH] Add Javadoc. Fixes #27 --- .../org/springframework/shell2/Bootstrap.java | 5 +++++ .../org/springframework/shell2/Commands.java | 6 ++++- .../springframework/shell2/ExitRequest.java | 5 ++++- .../springframework/shell2/MethodTarget.java | 4 +++- .../shell2/MethodTargetResolver.java | 7 +++++- .../shell2/ParameterResolver.java | 17 +++++++++++++- .../org/springframework/shell2/Shell.java | 8 ++++++- .../shell2/commands/package-info.java | 22 +++++++++++++++++++ .../JCommanderParameterResolver.java | 10 ++++----- .../shell2/jcommander/package-info.java | 22 +++++++++++++++++++ .../legacy/LegacyParameterResolver.java | 4 +++- .../shell2/legacy/package-info.java | 20 +++++++++++++++++ .../shell2/result/package-info.java | 22 +++++++++++++++++++ .../shell2/standard/ShellComponent.java | 2 +- .../shell2/standard/package-info.java | 22 +++++++++++++++++++ 15 files changed, 163 insertions(+), 13 deletions(-) create mode 100644 src/main/java/org/springframework/shell2/commands/package-info.java create mode 100644 src/main/java/org/springframework/shell2/jcommander/package-info.java create mode 100644 src/main/java/org/springframework/shell2/legacy/package-info.java create mode 100644 src/main/java/org/springframework/shell2/result/package-info.java create mode 100644 src/main/java/org/springframework/shell2/standard/package-info.java diff --git a/src/main/java/org/springframework/shell2/Bootstrap.java b/src/main/java/org/springframework/shell2/Bootstrap.java index 8590b94a..d2eb862e 100644 --- a/src/main/java/org/springframework/shell2/Bootstrap.java +++ b/src/main/java/org/springframework/shell2/Bootstrap.java @@ -36,6 +36,11 @@ import org.springframework.shell2.standard.EnumValueProvider; import org.springframework.shell2.standard.StandardParameterResolver; /** + * Main entry point for the application. + * + *

Creates the application context and start the REPL.

+ * + * @author Eric Bottard */ @SpringBootApplication @ComponentScan(basePackageClasses = {ArrayConverter.class, Bootstrap.class}, excludeFilters = @ComponentScan.Filter( diff --git a/src/main/java/org/springframework/shell2/Commands.java b/src/main/java/org/springframework/shell2/Commands.java index 0c9ef3d3..9129908c 100644 --- a/src/main/java/org/springframework/shell2/Commands.java +++ b/src/main/java/org/springframework/shell2/Commands.java @@ -20,7 +20,11 @@ import org.springframework.shell2.standard.ShellComponent; import org.springframework.shell2.standard.ShellMethod; /** - * Created by ericbottard on 27/12/15. + * Example commands for easy testing. + * + * To be removed in final project. + * + * @author Eric Bottard */ @ShellComponent("") public class Commands { diff --git a/src/main/java/org/springframework/shell2/ExitRequest.java b/src/main/java/org/springframework/shell2/ExitRequest.java index ada423a6..4dcecdec 100644 --- a/src/main/java/org/springframework/shell2/ExitRequest.java +++ b/src/main/java/org/springframework/shell2/ExitRequest.java @@ -33,7 +33,10 @@ public class ExitRequest extends RuntimeException { this.code = code; } + /** + * The exit code to be returned when the process exits. + */ public int status() { - return 0; + return code; } } diff --git a/src/main/java/org/springframework/shell2/MethodTarget.java b/src/main/java/org/springframework/shell2/MethodTarget.java index 846f7ea7..8db91da5 100644 --- a/src/main/java/org/springframework/shell2/MethodTarget.java +++ b/src/main/java/org/springframework/shell2/MethodTarget.java @@ -21,7 +21,9 @@ import java.lang.reflect.Method; import org.springframework.util.Assert; /** - * Created by ericbottard on 27/11/15. + * Represents a shell command behavior, i.e. code to be executed when a command is requested. + * + * @author Eric Bottard */ public class MethodTarget { diff --git a/src/main/java/org/springframework/shell2/MethodTargetResolver.java b/src/main/java/org/springframework/shell2/MethodTargetResolver.java index b70f693a..9c78dd3b 100644 --- a/src/main/java/org/springframework/shell2/MethodTargetResolver.java +++ b/src/main/java/org/springframework/shell2/MethodTargetResolver.java @@ -21,10 +21,15 @@ import java.util.Map; import org.springframework.context.ApplicationContext; /** - * Created by ericbottard on 09/12/15. + * Strategy interface for discovering commands. + * + * @author Eric Bottard */ public interface MethodTargetResolver { + /** + * Return a mapping from {@literal } to actual behavior. + */ public Map resolve(ApplicationContext context); } diff --git a/src/main/java/org/springframework/shell2/ParameterResolver.java b/src/main/java/org/springframework/shell2/ParameterResolver.java index 7fddaa62..a74f971b 100644 --- a/src/main/java/org/springframework/shell2/ParameterResolver.java +++ b/src/main/java/org/springframework/shell2/ParameterResolver.java @@ -21,16 +21,31 @@ import java.util.List; import org.springframework.core.MethodParameter; /** - * Created by ericbottard on 27/11/15. + * Implementations of this interface are responsible, once the command has been identified, of transforming the textual + * input to an actual parameter object. */ public interface ParameterResolver { + /** + * Should return true if this resolver recognizes the given method parameter (e.g. it + * has the correct annotation or the correct type). + */ boolean supports(MethodParameter parameter); + /** + * Turn the given textual input into an actual object, maybe using some conversion or lookup mechanism. + */ Object resolve(MethodParameter methodParameter, List words); + /** + * Describe a supported parameter, so that integrated help can be generated. + */ ParameterDescription describe(MethodParameter parameter); + /** + * Invoked during TAB completion. If the {@link CompletionContext} can be interpreted as the start + * of a supported {@link MethodParameter} value, one or several proposals should be returned. + */ List complete(MethodParameter parameter, CompletionContext context); } diff --git a/src/main/java/org/springframework/shell2/Shell.java b/src/main/java/org/springframework/shell2/Shell.java index 61ceb759..0e7f8130 100644 --- a/src/main/java/org/springframework/shell2/Shell.java +++ b/src/main/java/org/springframework/shell2/Shell.java @@ -19,11 +19,17 @@ package org.springframework.shell2; import java.util.Map; /** - * Created by ericbottard on 17/12/15. + * Implementing this interface allows sub-systems (such as the {@literal help} command) to + * discover available commands. + * + * @author Eric Bottard */ public interface Shell { + /** + * Return the mapping from command trigger keywords to implementation. + */ public Map listCommands(); } diff --git a/src/main/java/org/springframework/shell2/commands/package-info.java b/src/main/java/org/springframework/shell2/commands/package-info.java new file mode 100644 index 00000000..6965a1ea --- /dev/null +++ b/src/main/java/org/springframework/shell2/commands/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed 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. + */ + +/** + * Contains default commands that ought to apply to each shell app. + * + * @author Eric Bottard + */ +package org.springframework.shell2.commands; diff --git a/src/main/java/org/springframework/shell2/jcommander/JCommanderParameterResolver.java b/src/main/java/org/springframework/shell2/jcommander/JCommanderParameterResolver.java index db62899f..a4b857d6 100644 --- a/src/main/java/org/springframework/shell2/jcommander/JCommanderParameterResolver.java +++ b/src/main/java/org/springframework/shell2/jcommander/JCommanderParameterResolver.java @@ -36,7 +36,9 @@ import org.springframework.shell2.ParameterResolver; import org.springframework.util.ReflectionUtils; /** - * Created by ericbottard on 15/12/15. + * Provides integration with JCommander. + * + * @author Eric Bottard */ public class JCommanderParameterResolver implements ParameterResolver { @@ -50,8 +52,7 @@ public class JCommanderParameterResolver implements ParameterResolver { Class parameterType = parameter.getParameterType(); ReflectionUtils.doWithFields(parameterType, field -> { ReflectionUtils.makeAccessible(field); - boolean hasAnnotation = Arrays.asList(field.getAnnotations()) - .stream() + boolean hasAnnotation = Arrays.stream(field.getAnnotations()) .map(Annotation::annotationType) .anyMatch(JCOMMANDER_ANNOTATIONS::contains); isSupported.compareAndSet(false, hasAnnotation); @@ -60,8 +61,7 @@ public class JCommanderParameterResolver implements ParameterResolver { ReflectionUtils.doWithMethods(parameterType, method -> { ReflectionUtils.makeAccessible(method); - boolean hasAnnotation = Arrays.asList(method.getAnnotations()) - .stream() + boolean hasAnnotation = Arrays.stream(method.getAnnotations()) .map(Annotation::annotationType) .anyMatch(Parameter.class::equals); isSupported.compareAndSet(false, hasAnnotation); diff --git a/src/main/java/org/springframework/shell2/jcommander/package-info.java b/src/main/java/org/springframework/shell2/jcommander/package-info.java new file mode 100644 index 00000000..b3affc6d --- /dev/null +++ b/src/main/java/org/springframework/shell2/jcommander/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed 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. + */ + +/** + * Provides integration with JCommander. + * + * @author Eric Bottard + */ +package org.springframework.shell2.jcommander; diff --git a/src/main/java/org/springframework/shell2/legacy/LegacyParameterResolver.java b/src/main/java/org/springframework/shell2/legacy/LegacyParameterResolver.java index a37830cf..34bc960b 100644 --- a/src/main/java/org/springframework/shell2/legacy/LegacyParameterResolver.java +++ b/src/main/java/org/springframework/shell2/legacy/LegacyParameterResolver.java @@ -38,7 +38,9 @@ import org.springframework.stereotype.Component; import org.springframework.util.Assert; /** - * Created by ericbottard on 09/12/15. + * Resolves parameters by looking at the {@link CliOption} annotation and acting accordingly. + * + * @author Eric Bottard */ @Component public class LegacyParameterResolver implements ParameterResolver { diff --git a/src/main/java/org/springframework/shell2/legacy/package-info.java b/src/main/java/org/springframework/shell2/legacy/package-info.java new file mode 100644 index 00000000..b55252fa --- /dev/null +++ b/src/main/java/org/springframework/shell2/legacy/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed 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. + */ + +/** + * Provides integration with Spring Shell 1. + */ +package org.springframework.shell2.legacy; diff --git a/src/main/java/org/springframework/shell2/result/package-info.java b/src/main/java/org/springframework/shell2/result/package-info.java new file mode 100644 index 00000000..b010add4 --- /dev/null +++ b/src/main/java/org/springframework/shell2/result/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed 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. + */ + +/** + * Contains strategies for dealing with results of commands. + * + * @author Eric Bottard + */ +package org.springframework.shell2.result; diff --git a/src/main/java/org/springframework/shell2/standard/ShellComponent.java b/src/main/java/org/springframework/shell2/standard/ShellComponent.java index 4231985a..df10401b 100644 --- a/src/main/java/org/springframework/shell2/standard/ShellComponent.java +++ b/src/main/java/org/springframework/shell2/standard/ShellComponent.java @@ -25,7 +25,7 @@ import java.lang.annotation.Target; import org.springframework.stereotype.Component; /** - * Indicates that an annotated class may contain shell methods (themselves annotated with {@link @ShellMethod}) that + * Indicates that an annotated class may contain shell methods (themselves annotated with {@link ShellMethod}) that * is, * methods that may be invoked reflectively by the shell. * diff --git a/src/main/java/org/springframework/shell2/standard/package-info.java b/src/main/java/org/springframework/shell2/standard/package-info.java new file mode 100644 index 00000000..9317f8fc --- /dev/null +++ b/src/main/java/org/springframework/shell2/standard/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed 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. + */ + +/** + * Contains infrastructure for describing commands with the "new" preferred Spring Shell programming model. + * + * @author Eric Bottard + */ +package org.springframework.shell2.standard;