platformdoc/docs/components/component-specification/cdap-specification.md

   1 # Component specification (CDAP)
   2
   3 ## Overview
   4
   5 This page contains details specific to CDAP applications.
   6
   7 The component specification contains the following top-level groups of information:
   8
   9 * Component [Metadata](#metadata)
  10 * [Parameters](#Parameters): the section for specifying parameters in your AppConfig, AppPreferences, and ProgramPreferences to the Designer and Policy.
  11 * [Interfaces](#interfaces): the connections from this component to other components
  12 * [Auxiliary details](#auxiliary)
  13 * [List of artifacts](#artifacts)
  14
  15 Note: this page does not talk about [DCAE specific requirements](/components/component-type-cdap.md) that your component must adhere to. Please see that page for discussions about DMaaP, Policy, Metrics, and more.
  16
  17 ## Current Limitations and TODOs
  18
  19 * Currently we only support CDAP applications that have a stream.
  20 * The integration of DMD is likely to significantly change the [Interfaces](#interfaces) section in this specification, see [DMaaP abstraction](/components/component-type-cdap.md#dmaap-abstraction).
  21
  22 ## Metadata
  23
  24 See [Metadata](common-specification.md#metadata)
  25
  26 ## Parameters
  27
  28 There is a `parameters` section in your component specification. This section contains three optional keys: [app_config](#appconfig), [app_preferences](#apppreferences), and [propram_preferences](#prorgram_preferences):
  29 ```
  30 "parameters" : {
  31     "app_config" : [ ...],
  32     "app_preferences" : [ ...],
  33     "program_preferences" : [...]
  34     // any additional keys are ignored
  35 }
  36 ```
  37
  38 * Each section details the parameters that are a part of each of these CDAP constructs (see below).
  39 * All such parameters will be exposed to the designer and to policy for override.
  40 * These parameters should have default values specified by the component developer where necessary, i.e., parameters that _must_ come from the designer/policy should not have defaults.
  41 * All of these keys are optional because not every CDAP application uses preferences and not every application uses the AppConfig. However, you should specify at least one, or else your application will have no parameters exposed to policy or to the DCAE designer, which means it would be non-configurable.
  42 * Despite the AppConfig being optional to *specify* in the case that you have no parameters in your AppConfig, it is *required for processing* in your application. That is because the DCAE platform will place important information into your AppConfig as discussed below.
  43
  44 ### Parameter
  45 We use the following definition of a _single parameter_, which is used in several places below:
  46 ```
  47   {
  48       "name" : "param name",
  49       "value" : "developer default",
  50       "description" : "tell policy/ops what this does"
  51    }
  52 ```
  53
  54 ### AppConfig
  55
  56 The `app_config` key refers to the [CDAP AppConfig](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/configuration.html). It is expected to be a JSON:
  57 ```
  58 "app_config" : [ // list of JSON
  59     param1,      // see Parameter above
  60     ...
  61 ]
  62 ```
  63 Unfortunately, at the time of writing, the AppConfig is a Java map of `string:string`, which means you cannot have more complex structures (than string) as any value in your AppConfig.  However, there is a way to bypass this constraint: you can pass a JSON by encoding the JSON as a string. E.g., the `json.dumps()` and it's converse `loads` methods in Python:
  64 ```
  65 >>> import json
  66 >>> json.dumps({"foo" : "bar"})     # This is a real JSON
  67 '{"foo": "bar"}'                    # It is now a string: pass this in as your parameter value
  68 >>> json.loads('{"foo": "bar"}')    # Do the equivelent of this in your application
  69 {u'foo': u'bar'}                    # ...and you'll get back a real JSON
  70 >>>
  71 ```
  72
  73 The final AppConfig (after the designer and policy override parameter values) is passed into CDAP's AppConfig API when starting your application.
  74
  75 ### AppPreferences
  76
  77 In addition to the CDAP AppConfig, we support [Application Preferences](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/preferences.html#set-preferences).
  78 The format of the `app_preferences` value  is the same as the above:
  79 ```
  80 "app_preferences" : [   // list of JSON
  81     param1,             // see Parameter above
  82     ...
  83 ]
  84 ```
  85
  86 The final Application Preferences JSON (after the designer and policy override parameter values) is passed into CDAP's Preferences API when starting your application.
  87
  88 ### ProgramPreferences
  89
  90 Preferences can also be specified [per program](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/lifecycle.html#program-lifecycle) in CDAP. This key's value is a list of JSON with the following format:
  91 ```
  92 "program_preferences" : [                // note: this is a list of JSON
  93     {
  94       "program_id" :   "program name 1",  // the name of this CDAP program
  95       "program_type" : "e.g., flows",     // "must be one of flows, mapreduce, schedules, spark, workflows, workers, or services",
  96       "program_pref" : [                  // list of JSON
  97           param1,             // see Parameter above
  98           ...
  99       ]
 100     },
 101     // repeat for each program you want to pass a preferences JSON to
 102 ]
 103 ```
 104 Each `program_pref` JSON is passed into the CDAP API as the preference for `program_id`.
 105
 106 ## Interfaces
 107 See [Interfaces](common-specification.md#interfaces)
 108
 109 NOTE: for CDAP, this section is very likely to change when DMD  is available.
 110 The _future_ vision, as per [DMaaP intentionally abstracted](/components/component-type-cdap.md#dmaap-abstraction) is that you would publish your data as a series of files on HDFS, and DMD will pick them up and send them to the appropriate DMaaP feeds or directly when needed.
 111
 112 ## Auxiliary
 113
 114 `auxiliary` contains details about CDAP specific parameters.
 115
 116 Property Name | Type | Description
 117 ------------- | ---- | -----------
 118 streamname | string | *Required*.
 119 artifact_name | string |
 120 artifact_version | string | the version of your CDAP JAR artifact
 121 namespace | string | the CDAP namespace to deploy into, default is 'default'
 122 programs | array | contains each CDAP entity represented in the artifact
 123 program_type | string | CDAP entity (eg "flows")
 124 program_id | string | name of CDAP entity (eg "WhoFlow")
 125
 126 Example:
 127
 128 ```json
 129 +"auxiliary": {
 130     "streamname" : "who",
 131     "artifact_name" : "HelloWorld",
 132     "artifact_version" : "3.4.3",
 133     "namespace" : "hw",
 134     "programs" : [
 135                     {"program_type" : "flows", "program_id" : "WhoFlow"},
 136                     {"program_type" : "services", "program_id" : "Greeting"},
 137                     ...
 138                   ],
 139 }
 140 ```
 141 The `programs` key is identical to the `program_preferences` key discussed [above](#programpreferences) except:
 142
 143 * each JSON in the list does not contain `program_pref`
 144 * this is required! You must include all of your programs in this, as it is used to start each program as well as for DCAE to perform periodic healthchecks on your application. Don't forget about your services; they are programs too.
 145
 146 +
 147 ## Artifacts
 148
 149 `artifacts` contains a list of artifacts associated with this component.  This is where you specify your CDAP jar.
 150
 151 Property Name | Type | Description
 152 ------------- | ---- | -----------
 153 artifacts | JSON array | Each entry is a artifact object
 154
 155 Each artifact object has:
 156
 157 Property Name | Type | Description
 158 ------------- | ---- | -----------
 159 uri | string | *Required*. Uri to the artifact
 160 type | string | *Required*. For CDAP, use `jar`
 161
 162 This file is uploading using the CLI tool at the same time as your component specification.
 163