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

   1 # Component specification (CDAP)
   2
   3 The CDAP component specification contains the following groups of information. Many of these are common to both CDAP and Docker components and are therefore described in the common specification.
   4
   5 * [Metadata](common-specification.md#metadata)
   6 * [Interfaces](common-specification.md#interfaces) including the associated [Data Formats](/components/data-formats.md)
   7 * [Parameters](#parameters) - for specifying parameters in your AppConfig, AppPreferences, and ProgramPreferences to the Designer and Policy. This of course is CDAP-specific and is described below.
   8 * [Auxiliary Details](#auxiliary-details)
   9 * [List of artifacts](common-specification.md#artifacts)
  10
  11
  12 ## Current Limitations and TODOs
  13
  14 * The integration of DMD is likely to significantly change the [Interfaces](common-specification.md#interfaces) section in this specification..
  15
  16 ## Parameters
  17
  18 There is a `parameters` section in your component specification. This section contains three optional keys: [app_config](#appconfig), [app_preferences](#apppreferences), and [program_preferences](#programpreferences):
  19 ```
  20 "parameters" : {
  21     "app_config" : [ ...],
  22     "app_preferences" : [ ...],
  23     "program_preferences" : [...]
  24     // any additional keys are ignored
  25 }
  26 ```
  27
  28 * Each section details the parameters that are a part of each of these CDAP constructs (see below).
  29 * All such parameters will be exposed to the designer and to policy for override.
  30 * 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.
  31 * 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.
  32 * 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.
  33
  34 ### Parameter
  35
  36 The following CDAP specific definitions use `param1` to refer to the common parameter layout in [Parameter](common-specification.md#parameters)
  37
  38 ### AppConfig
  39
  40 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:
  41 ```
  42 "app_config" : [ // list of JSON
  43     param1,      // common parameter layout
  44     ...
  45 ]
  46 ```
  47 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:
  48 ```
  49 >>> import json
  50 >>> json.dumps({"foo" : "bar"})     # This is a real JSON
  51 '{"foo": "bar"}'                    # It is now a string: pass this in as your parameter value
  52 >>> json.loads('{"foo": "bar"}')    # Do the equivelent of this in your application
  53 {u'foo': u'bar'}                    # ...and you'll get back a real JSON
  54 >>>
  55 ```
  56
  57 The final AppConfig (after the designer and policy override parameter values) is passed into CDAP's AppConfig API when starting the application.
  58
  59 ### AppPreferences
  60
  61 In addition to the CDAP AppConfig, the platform supports [Application Preferences](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/preferences.html#set-preferences).
  62 The format of the `app_preferences` value  is the same as the above:
  63 ```
  64 "app_preferences" : [   // list of JSON
  65     param1,      // common parameter layout
  66     ...
  67 ]
  68 ```
  69
  70 The final Application Preferences JSON (after the designer and policy override parameter values) is passed into CDAP's Preferences API when starting your application.
  71
  72 ### ProgramPreferences
  73
  74 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:
  75 ```
  76 "program_preferences" : [                // note: this is a list of JSON
  77     {
  78       "program_id" :   "program name 1",  // the name of this CDAP program
  79       "program_type" : "e.g., flows",     // "must be one of flows, mapreduce, schedules, spark, workflows, workers, or services",
  80       "program_pref" : [                  // list of JSON
  81       param1,      // common parameter layout
  82           ...
  83       ]
  84     },
  85     // repeat for each program that receives a program_preferences JSON
  86 ]
  87 ```
  88 Each `program_pref` JSON is passed into the CDAP API as the preference for `program_id`.
  89
  90
  91 NOTE: for CDAP, this section is very likely to change when DMD  is available.
  92 The _future_ vision 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.
  93
  94 ## Auxiliary Details
  95
  96 `auxiliary` contains details about CDAP specific parameters.
  97
  98 Property Name | Type | Description
  99 ------------- | ---- | -----------
 100 streamname | string | *Required*.
 101 artifact_name | string |
 102 artifact_version | string | the version of your CDAP JAR artifact
 103 namespace | string | the CDAP namespace to deploy into, default is 'default'
 104 programs | array | contains each CDAP entity represented in the artifact
 105 program_type | string | CDAP entity (eg "flows")
 106 program_id | string | name of CDAP entity (eg "WhoFlow")
 107
 108 Example:
 109
 110 ```json
 111 "auxiliary": {
 112     "streamname" : "who",
 113     "artifact_name" : "HelloWorld",
 114     "artifact_version" : "3.4.3",
 115     "namespace" : "hw",
 116     "programs" : [
 117                     {"program_type" : "flows", "program_id" : "WhoFlow"},
 118                     {"program_type" : "services", "program_id" : "Greeting"},
 119                     ...
 120                   ],
 121 }
 122 ```
 123 The `programs` key is identical to the `program_preferences` key discussed [above](#programpreferences) except:
 124
 125 * each JSON in the list does not contain `program_pref`
 126 * 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.
 127