docs/developer_guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 Huawei Technologies Co., Ltd.
   4
   5 .. _cli_developer_guide:
   6
   7 CLI developer guide
   8 ===================
   9
  10 Develop OCLIP using plug-ins or YAML.
  11
  12 As a Plug-in
  13 -------------
  14 The plug-in approach is useful for implementing commands for products that do not support REST APIs.
  15 It uses this approach to provide the commands for its platform-related operations and provides the following commands as plug-ins:
  16
  17 * Schema-validate : To validate the OCS YAML
  18 * Schema-refresh: To enable the newly added commands
  19
  20 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
  21 HTTP commands, which helps to develop commands by **No coding, just by texting**
  22
  23 Follow the steps below to implement new plug-in commands for ONAP:
  24
  25 #. Create a new mvn module (ex: demo) under plugins project.
  26
  27 #. Use the plugins/sample project as a reference and update the new module demo project pom.xml file.
  28
  29 #. Add new command YAML with a unique name under 'src/main/resources/open-cli-schema'.
  30
  31 #. To implement a command as a plug-in, create a new plug-in class as follows: ::
  32
  33     package org.onap.cli.sample;
  34
  35     import java.util.Map;
  36
  37     import org.onap.cli.fw.OnapCommand;
  38     import org.onap.cli.fw.OnapCommandSchema;
  39     import org.onap.cli.fw.error.OnapCommandException;
  40     import org.onap.cli.fw.input.OnapCommandParameter;
  41
  42     /**
  43      * Hello world.
  44      */
  45     @OnapCommandSchema(name = "hello-world", version = "sample-1.0", schema = "hello-world.yaml")
  46     public class OnapHelloWorldCommand extends OnapCommand {
  47
  48         @Override
  49         protected void run() throws OnapCommandException {
  50             //Read the input arguments
  51             Map<String, OnapCommandParameter> paramMap = getParametersMap();
  52             OnapCommandParameter nameP = paramMap.get("name");
  53             String name = String.valueOf(nameP.getValue());
  54
  55             //Process command
  56             String output = "Hello " + name;
  57
  58             //Populate outputs
  59             this.getResult().getRecordsMap().get("output").getValues().add(output);
  60        }
  61     }
  62
  63 Note the following points:
  64
  65 * '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.
  66
  67 * getParametersMap() helps to get the arguments value given for a command before executing it
  68
  69 * getResult().getRecordsMap() helps to set the attributes values of command after executing it
  70
  71 #. Add the new plug-in class package path into the 'src/main/resources/META-INF/services/org.onap.cli.fw.OnapCommand' file
  72
  73 #. Now the command is ready. Build the project by running 'mvn clean install'. OCLIP framework automatically delivers these commands as part of the OCLIP zip file as part of this build.
  74
  75 #. To test this command, run the command 'oclip hello-world --name amsterdam'
  76
  77 As a YAML
  78 ---------
  79
  80 All OCLIP commands can be implemented as YAML using HTTP profile.
  81
  82 Follow the steps below to implement new commands for ONAP using YAML:
  83
  84 #. Install the latest OCLIP using the guide :ref:`cli_installation_guide`.
  85
  86 #. Under the open-cli-schema folder, add a new YAML file by referring to :ref:`open_cli_schema_version_1_0`.
  87
  88 #. Use the command 'oclip schema-validate' to validate the YAML before testing its functionality.
  89
  90 #. Run 'oclip schema-refresh' command to take the new YAML file. We recommended validating the YAML before running this command.
  91
  92 #. To test this command, run the command 'oclip CMD-NAME --help'.
  93
  94 Sample YAML
  95 ~~~~~~~~~~~~
  96
  97 Find more details about YAML specification at :ref:`open_cli_schema_version_1_0`.
  98
  99 Sample hello-world YAML ::
 100
 101     open_cli_schema_version: 1.0
 102
 103     name: hello-world-http
 104
 105     description: First cmd hello world using http running under lighttpd in cli at http://<cli-ip>:8080/version.json
 106
 107     version: sample-1.0
 108
 109     service:
 110         name: sample-service
 111         version: 1.0.0
 112         auth: none
 113         mode: direct
 114
 115     parameters:
 116         - name: name
 117           description: name of the person
 118           long_option: name
 119           short_option: b
 120           default_value: ${DEMO_NAME}
 121           type: string
 122           is_optional: false
 123
 124     results:
 125         direction: landscape
 126         attributes:
 127           - name: output
 128             description: hello world output
 129             type: string
 130             scope: short
 131
 132     http:
 133         request:
 134             uri: /version.json
 135             method: GET
 136         success_codes:
 137             - 200
 138             - 201
 139         result_map:
 140             output: Hello ${name}, You are running on $b{$.name} $b{$.version}
 141
 142         sample_response:
 143             body: {"name": "oclip", "version": "1.0"}