[incubator-hop-docs] branch asf-site updated: Basic metadata plugins documentation

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hansva pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-hop-docs.git


The following commit(s) were added to refs/heads/asf-site by this push:
     new 0ed27c7  Basic metadata plugins documentation
     new e372bf0  Merge pull request #5 from mattcasters/asf-site
0ed27c7 is described below

commit 0ed27c733dbe363e205e249dd59376105e3355dc
Author: Matt Casters <ma...@gmail.com>
AuthorDate: Thu Nov 12 20:53:49 2020 +0100

    Basic metadata plugins documentation
---
 hop-dev-manual/modules/ROOT/nav.adoc               |  1 +
 hop-dev-manual/modules/ROOT/pages/index.adoc       |  1 +
 .../modules/ROOT/pages/metadata-plugins.adoc       | 45 ++++++++++++++++++++++
 3 files changed, 47 insertions(+)

diff --git a/hop-dev-manual/modules/ROOT/nav.adoc b/hop-dev-manual/modules/ROOT/nav.adoc
index fa2b556..20fb892 100644
--- a/hop-dev-manual/modules/ROOT/nav.adoc
+++ b/hop-dev-manual/modules/ROOT/nav.adoc
@@ -1,4 +1,5 @@
 * xref:getting-started.adoc[Getting started]
 * xref:porting-kettle-plugins.adoc[Porting Kettle plugins]
+* xref:metadata-plugins.adoc[Metadata plugins]
 * xref:webhop/index.adoc[Webhop]
 ** xref:webhop/developer-guide.adoc[Webhop Developer Guide]
\ No newline at end of file
diff --git a/hop-dev-manual/modules/ROOT/pages/index.adoc b/hop-dev-manual/modules/ROOT/pages/index.adoc
index d1abb6d..2d0c0f7 100644
--- a/hop-dev-manual/modules/ROOT/pages/index.adoc
+++ b/hop-dev-manual/modules/ROOT/pages/index.adoc
@@ -2,3 +2,4 @@
 
 * xref:getting-started.adoc[Getting started]
 * xref:porting-kettle-plugins.adoc[Porting Kettle plugins]
+* xref:metadata-plugins.adoc[Metadata plugins]
diff --git a/hop-dev-manual/modules/ROOT/pages/metadata-plugins.adoc b/hop-dev-manual/modules/ROOT/pages/metadata-plugins.adoc
new file mode 100644
index 0000000..4964717
--- /dev/null
+++ b/hop-dev-manual/modules/ROOT/pages/metadata-plugins.adoc
@@ -0,0 +1,45 @@
+[[MetadataPlugins-MetadataPlugins]]
+= Metadata plugins
+
+Writing metadata plugins is easy in Hop.  Any Plain Old Java Object can be used as a starting point.
+
+== @HopMetadata Annotation
+
+This annotation signals to the Metadata plugin type that there is something worth looking at.  The class which carries this annotation will contain the metadata.
+
+Here are the attributes of the @HopMetadata annotation:
+
+* key : this uniquely identifies the plugin and will be the name of the folder in which the metadata resides when serialising to JSON (see below)
+* name : a human readable name
+* description : an extended description
+* iconImage : the path to an image which helps identify the metadata in the Hop GUI
+
+The class with this annotation will be found either because it lives in the ```plugins/``` folder of Hop or if it's an internal class and is described in the file ```engine/src/main/resources/hop-metadata-plugins.xml```
+
+Example: https://github.com/apache/incubator-hop/blob/f8f2ad2d0bc0cfd143ae90cc32e73b6c9e1cda78/engine/src/main/java/org/apache/hop/partition/PartitionSchema.java#L47[PartitionSchema.java]
+
+
+== The dialog to edit the metadata
+
+You also want to have a dialog to edit the metadata.  This can be any old SWT dialog as long as it implements the IMetadataDialog interface it will be picked up.
+
+Example: https://github.com/apache/incubator-hop/blob/2e16685ad80a3bc213d796366316d18f7bfd74d2/ui/src/main/java/org/apache/hop/ui/partition/PartitionSchemaDialog.java#L71[PartitionSchemaDialog.java]
+
+The path to the Dialog class will be found automatically by looking at the name of the metadata class and then simply by appending Dialog to it.
+If you prefer to keep metadata and GUI code separate the Hop GUI will also look in package ```org.apache.hop.ui``` instead of ```org.apache.hop```
+
+Working examples:
+
+* ```org.apache.hop.path.to.MyMetadata```  -> ```org.apache.hop.path.to.MyMetadataDialog```
+* ```org.apache.hop.my.plugin.MyMetadata```  -> ```org.apache.hop.ui.my.plugin.MyMetadataDialog```
+
+== Metadata serialisation
+
+As mentioned above, the key or ID the @HopMetadata plugin is used as a top level folder to store objects in.
+For the serialisation to JSON most simple data types are supported. However we suggest you use the KISS principle.
+If you want to serialize interfaces (for example like IDatabase used by DatabaseMeta) you might want to flag the interface with the @HopMetadataObject annotation.
+This annotation allows you to specify an object factory for those classes.  Such an object factory implements interface ```IHopMetadataObjectFactory``` with the 2 following methods:
+
+* ```public Object createObject( String id, Object parentObject ) throws HopException``` -> Creates an object using an ID.  The parent object is often another metadata object.  You can use it to check if it implements IVariables so you can inherit variables from there.
+* ```public String getObjectId( Object object ) throws HopException``` -> Retrieves the object ID from the given object. We recommend that you check the instance of the object until the factory interface supports generics. (TODO)
+