From e67a11562404dcc77005c939f46d1acff79e9b61 Mon Sep 17 00:00:00 2001 From: Robert Lucarini Date: Tue, 14 Apr 2020 10:38:47 -0700 Subject: [PATCH 1/2] Removed schema and Get mentions --- java-sdk/configuration.asciidoc | 76 +++------------------------------ 1 file changed, 5 insertions(+), 71 deletions(-) diff --git a/java-sdk/configuration.asciidoc b/java-sdk/configuration.asciidoc index 8e6b4224..797fa8b2 100644 --- a/java-sdk/configuration.asciidoc +++ b/java-sdk/configuration.asciidoc @@ -7,11 +7,11 @@ To build a valid connector configuration, you must: * Apply a few annotations. * Define connector "getter" methods and annotations. -All methods that are annotated with `@Property` and start with "get" are considered to be configuration properties. -For example, `@Property() String getName();` results in a String property called `name`. +All methods that are annotated with `@Property` and are considered to be configuration properties. +For example, `@Property() String name();` results in a String property called `name`. This property would then be present in the generated schema. -Here is an example of the most basic configuration, along with required annotations and a sample "getter" method: +Here is an example of the most basic configuration, along with required annotations and a sample property access methods: ```java @RootSchema( @@ -26,7 +26,7 @@ public interface MyConfig extends ConnectorConfig { title = "Properties", required = true ) - public Properties getProperties(); + public Properties properties(); /** * Connector specific settings @@ -37,7 +37,7 @@ public interface MyConfig extends ConnectorConfig { title = "My custom property", description = "My custom property description" ) - public Integer getMyCustomProperty(); + public Integer myCustomProperty(); } @@ -53,69 +53,3 @@ Once a connector configuration has been defined, it can be associated with the ` From that point, the framework takes care of providing the configuration instances to your connector. It also generates the schema, and sends it along to Fusion when it connects to Fusion. -=== About com.lucidworks.schema -The `com.lucidworks.schema` project (included in the connectors SDK) aims to simplify the process of creating JSON Schemas. -It also provides utilities for building type-safe POJOs from schema definitions. - -The basic idea here is that you create an interface that extends `Model`, add property getters, and then add a few annotations. -Once your interface has been built, you can generate an `ObjectType` instance, which is the object that contains all of the JSON schema metadata. -By then combining that schema object with a `Map`, you can create instances of your interface to use as configuration objects. - -The configuration objects are based on `java.lang.reflect.Proxy`, which is what the `ModelGenerator` returns. -Most method calls to these proxy instances result in method calls to the underlying `Map`. -For example, if the interface defines a `getId` method, then a runtime call results in a call to the `Map`: `data.get("id")`. - -A few special cases exist: - -* `toString` is proxied directly to the `Map` -* `getClass` returns the class of the interface provided to `ModelGenerator#generate()` -* `_data` returns the underlying `Map` object -* If the method starts with `set`, the arguments are captured and sent to the underlying map via `put()` - -Here is a simple example: - -```java -interface MyConfig extends Model { - - @Property - @StringSchema(minLength=1) - String getId(); - -} -``` - -Create the schema: - -```java -class Runner { - public static void main(String[] args){ - ObjectType schema = SchemaGenerator.generate(MyConfig.class); - } -} -``` - -Generate an instance of the `MyConfig` class: - -```java -class Runner { - public static void main(String[] args){ - Map data = new java.util.HashMap<>(); - data.put("id", 100); - MyConfig config = ModelGenerator.generate(MyConfig.class, data); - System.out.println("id -> " + config.getId()); - } -} -``` - -Schema metadata can be applied to properties using additional annotations. For example, applying limits to the min/max length of a string, or describing the types of items in an array. - -Nested schema metadata can also be applied to a single field by using "stacked" schema based annotations: - -```java -interface MySetConfig extends Model { - @SchemaAnnotations.Property(title = "My Set") - @SchemaAnnotations.ArraySchema(defaultValue = "[\"a\"]") - @SchemaAnnotations.StringSchema(defaultValue = "some-set-value", minLength = 1, maxLength = 1) - Set getMySet(); - } -``` From 3c98a955350f272abe6919460d5442b73a3892b0 Mon Sep 17 00:00:00 2001 From: Robert Lucarini Date: Fri, 17 Apr 2020 17:47:43 -0700 Subject: [PATCH 2/2] APOLLO -24186 Updates to schema and configuration information (#72) Updating documentation on connector configurations and schemas. --- java-sdk/configuration.asciidoc | 37 +++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/java-sdk/configuration.asciidoc b/java-sdk/configuration.asciidoc index 797fa8b2..40a84a56 100644 --- a/java-sdk/configuration.asciidoc +++ b/java-sdk/configuration.asciidoc @@ -4,14 +4,14 @@ To build a valid connector configuration, you must: * Define an interface. * Extend `ConnectorConfig`. -* Apply a few annotations. * Define connector "getter" methods and annotations. +* Apply property related annotations. All methods that are annotated with `@Property` and are considered to be configuration properties. For example, `@Property() String name();` results in a String property called `name`. This property would then be present in the generated schema. -Here is an example of the most basic configuration, along with required annotations and a sample property access methods: +Here is an example of the most basic configuration, along with required annotations and sample property access methods: ```java @RootSchema( @@ -53,3 +53,36 @@ Once a connector configuration has been defined, it can be associated with the ` From that point, the framework takes care of providing the configuration instances to your connector. It also generates the schema, and sends it along to Fusion when it connects to Fusion. +=== About com.lucidworks.schema +The `com.lucidworks.schema` library, which is exposed by the connectors SDK, aims to simplify the process of creating JSON schemas and typed configurations. + +The main idea is that you create an interface that extends `Model`, add property getter methods, and a few annotations to describe property constraints and validation rules. The connector SDK provides a base interface, `ConnectorConfig`, which extends `Model`. + +A configuration type is associated to a connector by calling `ConnectorPlugin.builder(MyConnectorConfig.class)`, you can see an example link:java-sdk/connectors/random-connector/src/main/java/com/lucidworks/connector/plugins/random/RandomContentPlugin.java#L27[here]. This is what makes it possible for the runtime framework to create and provide instances of the configuration, or datasource, when the connector runs. + +The connector runtime also uses these `Model` based interfaces to generate plugin specific schemas. Schemas are used by Fusion in many different ways, but perhaps the most useful is the Fusion Admin UI. The HTML forms used for creating and updating Fusion datasources are dynamically generated from plugin schemas. + +Here is a simple example: + +```java +interface MyConfig extends Model { + + @Property + @StringSchema(minLength=1) + String id(); + +} +``` + +Schema metadata can be applied to properties using additional annotations. For example, applying limits to the min/max length of a string, or describing the types of items in an array. + +Nested schema metadata can also be applied to a single field by using "stacked" schema based annotations: + +```java +interface MySetConfig extends Model { + @SchemaAnnotations.Property(title = "My Set") + @SchemaAnnotations.ArraySchema(defaultValue = "[\"a\"]") + @SchemaAnnotations.StringSchema(defaultValue = "some-set-value", minLength = 1, maxLength = 1) + Set mySet(); + } +```