From 669915c559fb9bcd4a8f8d5239f0b9b6ab33436b Mon Sep 17 00:00:00 2001 From: Dinh Danh Le Date: Sun, 5 Aug 2018 09:54:13 +0100 Subject: Adding Apex docs for Plugins module Change-Id: Icf68473b472a5896972de5b07b275682a77a1c9f Signed-off-by: Dinh Danh Le Issue-ID: POLICY-867 --- .../adoc/fragments/ctx-schema-avro-config.adoc | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs/adoc/fragments/ctx-schema-avro-config.adoc (limited to 'plugins/plugins-context/plugins-context-schema/plugins-context-schema-avro/src/site-docs') 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 -- cgit 1.2.3-korg