docs/developer_guide.rst

   1 .. _developer_guide:
   2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2017 Huawei Technologies Co., Ltd.
   5
   6 CLI developer guide
   7 ===================
   8
   9 Develop ONAP CLI using plug-ins or YAML.
  10
  11 As a Plug-in
  12 -------------
  13 The plug-in approach is useful for implementing commands for products that do not support REST APIs.
  14 It uses this approach to provide the commands for its platform-related operations and provides the following commands as plug-ins:
  15
  16 * Schema-validate : To validate the OCS YAML
  17 * Schema-refresh: To enable the newly added commands
  18
  19 It also offers the flexibility to implement any kind of command. For example, a specific plug-in command is provided in the CLI to handle
  20 HTTP commands, which helps to develop commands by **No coding, just by texting**
  21
  22 Follow the steps below to implement new plug-in commands in ONAP:
  23
  24 #. Create a new mvn module (ex: demo) under plugins project.
  25
  26 #. Use the plugins/sample project as a reference and update the new module demo project pom.xml file.
  27
  28 #. Add new command YAML with a unique name under 'src/main/resources/onap-cli-schema'.
  29
  30 #. To implement a command as a plug-in, create a new plug-in class as follows: ::
  31
  32     package org.onap.cli.sample;
  33
  34     import java.util.Map;
  35
  36     import org.onap.cli.fw.OnapCommand;
  37     import org.onap.cli.fw.OnapCommandSchema;
  38     import org.onap.cli.fw.error.OnapCommandException;
  39     import org.onap.cli.fw.input.OnapCommandParameter;
  40
  41     /**
  42      * Hello world.
  43      */
  44     @OnapCommandSchema(name = "hello-world", version = "sample-1.0", schema = "hello-world.yaml")
  45     public class OnapHelloWorldCommand extends OnapCommand {
  46
  47         @Override
  48         protected void run() throws OnapCommandException {
  49             //Read the input arguments
  50             Map<String, OnapCommandParameter> paramMap = getParametersMap();
  51             OnapCommandParameter nameP = paramMap.get("name");
  52             String name = String.valueOf(nameP.getValue());
  53
  54             //Process command
  55             String output = "Hello " + name;
  56
  57             //Populate outputs
  58             this.getResult().getRecordsMap().get("output").getValues().add(output);
  59        }
  60     }
  61
  62 Note the following points:
  63
  64 * 'org.onap.cli.sample.OnapHelloWorldCommand' extends 'OnapCommand' and is annotated with OnapCommandSchema, which carries the command name, product version and schema file name, and is placed under the 'src/main/resources/onap-cli-schema' folder.
  65
  66 * getParametersMap() helps to get the arguments value given for a command before executing it
  67
  68 * getResult().getRecordsMap() helps to set the attributes values of command after executing it
  69
  70 #. Add the new plug-in class package path into the 'src/main/resources/META-INF/services/org.onap.cli.fw.OnapCommand' file
  71
  72 #. Now the command is ready. Build the project by running 'mvn clean install'. ONAP CLI framework automatically delivers these commands as part of the ONAP CLI zip file as part of this build.
  73
  74 #. To test this command, run the command 'onap hello-world --name amesterdam'
  75
  76 As a YAML
  77 ---------
  78
  79 All ONAP CLI commands can be implemented as YAML using HTTP profile.
  80
  81 Follow the steps below to implement new commands in ONAP using YAML:
  82
  83 #. Install the latest ONAP CLI using the guide installation_guide_.
  84
  85 #. Under the onap-cli-schema folder, add a new YAML file by referring to open_cli_schema_version_1_0_.
  86
  87 #. Use the command 'onap schema-validate' to validate the YAML before testing its functionality.
  88
  89 #. Run 'onap schema-refresh' command to take the new YAML file. We recommed validating the YAML before running this command.
  90
  91 #. To test this command, run the command 'onap CMD-NAME --help'.