summaryrefslogtreecommitdiffstats
path: root/plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs
diff options
context:
space:
mode:
authorDinh Danh Le <dinh.danh.le@ericsson.com>2018-08-05 09:54:13 +0100
committerDinh Danh Le <dinh.danh.le@ericsson.com>2018-08-05 09:57:29 +0100
commit669915c559fb9bcd4a8f8d5239f0b9b6ab33436b (patch)
tree0d0dec28fad650390a9dd6fe2df1e8b00e9e3f22 /plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs
parent0f0f41071ae3c6c7896c7770b0139c9c40866330 (diff)
Adding Apex docs for Plugins module
Change-Id: Icf68473b472a5896972de5b07b275682a77a1c9f Signed-off-by: Dinh Danh Le <dinh.danh.le@ericsson.com> Issue-ID: POLICY-867
Diffstat (limited to 'plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs')
-rw-r--r--plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs/adoc/fragments/ctx-schema-avro-config.adoc49
1 files changed, 49 insertions, 0 deletions
diff --git a/plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs/adoc/fragments/ctx-schema-avro-config.adoc b/plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs/adoc/fragments/ctx-schema-avro-config.adoc
new file mode 100644
index 000000000..72bd8b9d9
--- /dev/null
+++ b/plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs/adoc/fragments/ctx-schema-avro-config.adoc
@@ -0,0 +1,49 @@
+//
+// ============LICENSE_START=======================================================
+// Copyright (C) 2016-2018 Ericsson. All rights reserved.
+// ================================================================================
+// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
+// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
+//
+// SPDX-License-Identifier: CC-BY-4.0
+// ============LICENSE_END=========================================================
+//
+// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
+//
+
+== Configure AVRO Schema Handler
+
+The AVRO schema handler is added to the configuration as follows:
+
+[source%nowrap,json]
+----
+"engineServiceParameters":{
+ "engineParameters":{
+ "contextParameters":{
+ "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
+ "schemaParameters":{
+ "Avro":{
+ "parameterClassName" :
+ "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
+ }
+ }
+ }
+ }
+}
+----
+
+Using the AVRO schema handler has one limitation: AVRO only supports field names that represent valid Java class names.
+This means only letters and the character `_` are supported.
+Characters commonly used in field names, such as `.` and `-`, are not supported by AVRO.
+for more information see link:https://avro.apache.org/docs/1.8.1/spec.html#names[Avro Spec: Names].
+
+To work with this limitation, the APEX Avro plugin will parse a given AVRO definition and replace _all_ occurrences of `.` and `-` with a `_`.
+This means that
+
+- In a policy model, if the AVRO schema defined a field as `my-name` the policy logic should access it as `my_name`
+- In a policy model, if the AVRO schema defined a field as `my.name` the policy logic should access it as `my_name`
+- There should be no field names that convert to the same internal name
+ ** For instance the simultaneous use of `my_name`, `my.name`, and `my-name` should be avoided
+ ** If not avoided, the event processing might create unwanted side effects
+- If field names use any other not-supported character, the AVRO plugin will reject it
+ ** Since AVRO uses lazy initialization, this rejection might only become visible at runtime