Merge pull request #297 from cmgrote/master

Updated docs with architectural view and getting started guide

README.md

@@ -15,102 +15,28 @@ This repository houses the ODPi Egeria connectors for various Hadoop ecosystem c
 - [Apache Ranger](https://ranger.apache.org) is a framework to enable, monitor and manage comprehensive data security
     across the Hadoop platform.  (Coming soon.)
 
-## Getting started
+## Quick links
 
-### TL;DR
+- See our [Getting Started](https://odpi.github.io/egeria-connector-hadoop-ecosystem/getting-started/index.html) guide for
+  step-by-step instructions on using these connectors to integrate Apache Atlas with Egeria.
+- See the [CTS Results](cts/README.md) for details on its conformance.
 
-The quick version:
+## How it works
 
-1. Download the latest connectors from: https://odpi.jfrog.io/odpi/egeria-snapshot-local/org/odpi/egeria/egeria-connector-hadoop-ecosystem-package/2.7-SNAPSHOT/egeria-connector-hadoop-ecosystem-package-2.7-SNAPSHOT-jar-with-dependencies.jar
-1. Download the latest Egeria core from: https://odpi.jfrog.io/odpi/egeria-snapshot-local/org/odpi/egeria/server-chassis-spring/2.7-SNAPSHOT/server-chassis-spring-2.7-SNAPSHOT.jar
-1. Rename the downloaded Egeria core file to `egeria-server-chassis-spring.jar`.
-1. Download the `truststore.p12` file from: https://github.com/odpi/egeria/blob/master/truststore.p12
-1. Run the following command to start Egeria from the command-line, waiting for the final line of output indicating the
-    server is running and ready for configuration:
-    ```bash
-    $ export STRICT_SSL=false
-    $ java -Dloader.path=. -jar egeria-server-chassis-spring.jar
-     ODPi Egeria
-        ____   __  ___ ___    ______   _____                                 ____   _         _     ___
-       / __ \ /  |/  //   |  / ____/  / ___/ ___   ____ _   __ ___   ____   / _  \ / / __    / /  / _ /__   ____ _  _
-      / / / // /|_/ // /| | / / __    \__ \ / _ \ / __/| | / // _ \ / __/  / /_/ // //   |  / _\ / /_ /  | /  _// || |
-     / /_/ // /  / // ___ |/ /_/ /   ___/ //  __// /   | |/ //  __// /    /  __ // // /  \ / /_ /  _// / // /  / / / /
-     \____//_/  /_//_/  |_|\____/   /____/ \___//_/    |___/ \___//_/    /_/    /_/ \__/\//___//_/   \__//_/  /_/ /_/
+There is currently only an Apache Atlas connector. This connector integrates into the Open Connector Framework (OCF) and
+implements certain methods that adhere to the interfaces required by a repository proxy. These then communicate with
+Apache Atlas via Apache Atlas's Java client (in turn communicating via Apache Atlas's REST API) to read information
+from an Apache Atlas environment.
 
-     :: Powered by Spring Boot (v2.2.2.RELEASE) ::
+This requires an existing Apache Atlas environment to already be running elsewhere: the connector simply connects to
+this existing environment and "proxies" any requests from Egeria into a series of native API calls against the environment.
 
+![Overview](docs/overview.png)
 
-    No OMAG servers listed in startup configuration
-    Thu Jan 02 11:30:10 GMT 2020 OMAG server platform ready for more configuration
-    ```
-1. Follow the detailed instructions for configuring the connector(s) you want to use, either [Apache Atlas](apache-atlas-adapter)
-   or Apache Ranger (coming soon).
+> Overview of the connector implementation
 
-### Obtain the connector
-
-You can either download the latest released or snapshot version of the connector directly from ODPi, or build the
-connector yourself. In both cases, once you have the jar file for the connector
-(`egeria-connector-hadoop-ecosystem-package-VERSION-jar-with-dependencies.jar`) this needs to be copied to a
-location where it can be run alongside the OMAG Server Platform from Egeria core itself. For example, this could be
-placing the file into the `/lib` directory as `/lib/egeria-connector-hadoop-ecosystem-package-VERSION-jar-with-dependencies.jar`.
-
-#### Download from ODPi
-
-To download a pre-built version of the connector, use either of the following URLs (depending on whether you want an
-officially-released version or the latest snapshot):
-
-- Release: https://odpi.jfrog.io/odpi/egeria-release-local/org/odpi/egeria/egeria-connector-hadoop-ecosystem-package/2.5/egeria-connector-hadoop-ecosystem-package-2.5-jar-with-dependencies.jar
-- Snapshot: https://odpi.jfrog.io/odpi/egeria-snapshot-local/org/odpi/egeria/egeria-connector-hadoop-ecosystem-package/2.7-SNAPSHOT/egeria-connector-hadoop-ecosystem-package-2.7-SNAPSHOT-jar-with-dependencies.jar
-
-#### Building the connector yourself
-
-Alternatively, you can build the connector yourself. To do this, you'll need to first clone this repository and then
-build through Maven using `mvn clean install`. After building, the connector is available as:
-
-```text
-distribution/target/egeria-connector-hadoop-ecosystem-package-VERSION-jar-with-dependencies.jar
-```
-
-### Configure security
-
-There are [multiple options to configure the security of your environment](docs/security/README.md) for this connector,
-but this must be done prior to starting up the connector itself (step below).
-
-For simple tests, if you can run your Apache Atlas environment with only its most basic security and without HTTPS, then
-there is nothing additional you need to configure for the connector.
-
-Alternatively, if you can still use basic authentication (username and password) but must run Apache Atlas via HTTPS,
-and you simply want to test things out, the simplest (but most insecure) option is to set the environment variable
-`STRICT_SSL` to `false` using something like the following prior to starting up the OMAG Server Platform:
-
-```bash
-export STRICT_SSL=false
-```
-
-Note that this will disable all certificate validation for SSL connections made between Egeria and your Apache Atlas
-environment, so is inherently insecure.
-
-Note that in any case, having a `truststore.p12` file available to the server chassis is required -- the simplest is to
-ensure that Egeria's own (https://github.com/odpi/egeria/blob/master/truststore.p12) is placed in the directory in which
-you are running the server chassis.
-
-### Startup the OMAG Server Platform
-
-You can startup the OMAG Server Platform with this connector ready-to-be-configured by running:
-
-```bash
-$ java -Dloader.path=/lib -jar server-chassis-spring-VERSION.jar
-```
-
-(This command will startup the OMAG Server Platform, including all libraries
-in the `/lib` directory as part of the classpath of the OMAG Server Platform.)
-
-### Configure the connector(s) you want to use
-
-See the detailed instructions for configuring the connector(s) you want to use:
-
-- [Apache Atlas](apache-atlas-adapter)
-- Apache Ranger (coming soon)
+Note that the connector operates only in a read-only manner: no write operations (creates or updates) are implemented
+against Apache Atlas. Furthermore, [only a subset of the open metadata types are currently mapped](docs/mappings/README.md).
 
 ----
 License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),

docs/HadoopEcosystemConnectors.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2021-05-28T08:35:57.783Z" agent="5.0 (Macintosh; Intel Mac OS X 11_3_1) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/14.6.13 Chrome/89.0.4389.128 Electron/12.0.7 Safari/537.36" etag="qJ8bglCjCmmn9GjFld_6" version="14.6.13" type="device" pages="3"><diagram id="5z1nvSjVh-oLaUZI1JB8" name="Overview">3Vpdc9o4FP01zLQPyeBveKSEbbttZumy2bb7siOwwJoIi5FFCP31K2H5S5Jt0rVJUvIQ61oS0j336B5JDJzp9vE9BbvoloQQD+xh+Dhwbga2bVlDn/8TlmNqGY+D1LChKJSVCsMC/YDSOJTWPQphUqnICMEM7arGFYljuGIVG6CUHKrV1gRXv3UHNlAzLFYA69avKGRRah3ZQWH/ANEmyr7Z8sfpmy3IKsuZJBEIyaFkcmYDZ0oJYenT9nEKsXBe5pe03W81b/OBURizcxoM13fLxd//WF8+/Tv9YseH4356dyV7eQB4Lyc82YFVBLltwjBI5NDZMfMHJfs4hKJLa+C8O0SIwQVvId4eeARwW8S2WL5O7iFbRbIA6ErCG4gSRpuYP6/46CEVdXkvKN58hmsxG49bHiBliCMxkVUZEd3LAfN38LHWE1buXx6YkGwho0deRTZwAgmJjElnKMuHAmHHl7aohK7tSiOQUbXJ+y4czx+k75+Ag63hMNtAigC3/XE7ec//zTFga0K3A9vHfDjvlpQ/bcTTmwWk3B+8zjQCSYKSt3odk6UHZMclZPEJyTNwXRLGyLYbaMftyNqXRdZpZVi2dhHaISZrhPGUYN6n6MgJPTgKXVGJUXIPS29G9tLx/Vq6FdiOTKztADLLVzCzdcyskQGzvGHnmLkaZreQgRAwoPNoDimnHIMxR6U3+NZr6K9WJvjCYLzkQa7Dt0VhKMahsLMDwFxbAcw3AOZcFDCvAbAh9xbm9EIkflZ+dUEVNXF5Bs+bljenL8f7muP/hCDUZUPJjfARsW+l5+/8eXjtydKNmOowKxyzQswH+61cSFvZXlYu2p1KWcM1iZmMfsuuXeTqQauFuRwLMOSSUc6VUBaRDYkBnhVWib2o14w89xnZ0xVsD3UG6AayhnpuYyRdcd9Zjl+JpitLjybPEEyZjUIuSdBDdUqmCJOjmBPEJ5sPQc3Vru9cW7ZX7SZ1h2xZFrdKZ8EouPaq3FBjPvWY1tWEUnAsVduJCkn9sB01Xfle48jU+u6wItP5QzoCc2ur2jiHKBstWa8TyAYqjXPAf57ZwU8wu4al/5ekeSrTeOqfPoZ86Ym/p/NUjKTUTfrh9hAkUZ4mzidzK0m9NpJa/HNJUlpKbrdHSsCdS8gszAua+NcquTtipDpmhZF1DOufQhlZyxyaLf4Syn/+UQh/8Y1c/mME5QSfTT1GhKIfPPgBlpzsQK142kpp2IyZZGLQl1qx9G32XQL1bVcSgZ143G/x5LQvK9akz2AJ8Zwk6KQnS5tXs7IoIUT2DKOYez87qBJurmJcj08dooW411RJBwj6it50DQrBNSCoLhrdAajvpqcUAgZzNqnbs7td2PT6BmJ4en1GVssL3WS1GunZCvkTU1o1QjLxnSnsdCqO8mnW4rzAN72IIyqOAEqrRScpUe69W3VwyuXG3On7QVU9GU4WesylGntURXp2LlUTXNBPItUG7J4lVS+QSPUDmcvRvsT07xWiv0ba5/vsfCo98fxM/v4KG9nAVTSzesx1Ls81wdQXz9VT8irP9fVn1Fj/xW5hLf106itccsPdxxektjvSaq7i5/z8o3w2aBJrdm9iTT9C0K4+fgcPIN8CvRxMOtoBOSpxDDsg00F5f/p5pEEyezh5fngLdjvDVuiVn5BnEub5TsitsebyOYVXyz3Cwu18qYQbCsRuUvDhzQeRh+ypyLJs9fZZGXHBGyVHQS0woGYZUOvtQimbQ5ko2yUMhe/t4Sewvge//GrlGm6XLrpa2fpxzTQC8aZFuBu3uMGZF0yX2eS/4PsludVqleVpKqkNJu46u6r7PC2YetTkjtsipc/ee6tLkypfu7pWUhPXqFmTa/W9F3LobRuO6NpJ+8qugMxrTPMS0yFHW7j3HPdGCk3yy90nX+Saw7rzOyOV1l7zLW5L/T7oxovFj0PT6sVPbJ3Zfw==</diagram><diagram id="zbQFHPY_3O7AILBR8jvU" name="Page-2">5Vnbcts2EP0azbQP9hC8iXqUFSVNHE81VTtO+wYRIIkxSKggbEn++i5M8E5ZtiM6mSn9IOBwsVrs2YOLPHEW6f6TxNvkRhDKJ7ZF9hPnw8S2EbJ8+NDIoUBms2kBxJIRY1QDa/ZIDWgZ9J4RmrcMlRBcsW0bDEWW0VC1MCyl2LXNIsHb37rFMe0B6xDzPnrLiEoKNLCnNf4bZXFSfjPyZ8WbFJfGZiZ5gonYNSBnOXEWUghVtNL9gnKdvDIvj3mqDleHRNofgxv32o03i91F4ezja4ZUU5A0U292Pb8it3GyimbyK77+8i9C83/mZoj1gPm9ydd8i8OEAjZXHOdm5upQplOK+4xQ7RJNnKtdwhRdwwj9dgcFBFiiUm5e53dUhYnpYBma6pjqHmdxBu0QpkSltgUvLIu/0khP0QPkgUrFgMi5MVVCuzcBwzu67zB8Ij2o4gyKnYqUKnmAccaLMzW5MHXuWKa/q6vG8Q2WNCrGdg2ITaXGle+aDWgYQl5BDuqRs4ypZBiw32/mn+BjxbGKhEwnts8hnKuNhFasW7+sqYQkgc0iwXnO8l/7NkPICHTPGnTzJ3pfQPZGKCXSEfmenabbfl+67ZNaLBdJIc9IVMQ4XwgOPrUjh3g0IK42UlLc0cabwN44vn9UmDXhwZC+x+IR+R0i7T6RKBggshp4diKdHpE3VGGCFe4rbkUliFPRDKgajdMoon4YDnFKprMNVH6f05QRouPo6HgsFl27w6I/wKLzriy6z7BoQQo5CJGJ7IcqcTRRdTdDb4COodXRGYsNr8fGHxST/vmkkVu6Z+pbo/03tK1Lz/Q+6KlaZedQdjII9luzU4yyvbJfj3vqlQMjkSmjE2QfXSOPM3mU+2aBUAJHWzNXIVUiYpFhvqxRUxDa7g3lAIkU9zKkz9BgRKGwjKk6tQQeLa8LSChy/FaJXaB+iXkDFVZiksLZhz205zlUdiaKlWCQgSqE7v7v+s4lsr22myIdZmTzaN1xNg2ml15bMF0hFBnruZpLiQ8Ns602yI+H7XR3O997NrKuvWu1LgnQKCIYHo3agyuKymhFFOVUTbrargh/u9z9N8j9iHS/V7nVTtgTr//0DGy3nv57vXh1JA03xQM4wXlSbSjfqfCTynVPKRfB855KRZ2jgR10qvClKi1rv9aOf9lV/Jlk2o25I9NjshtfV9O+rpbrP/UNY/VZXzD0F8I1gzNq5vfDDqSJkOwRBIG50elYZx2vt6QO3ASHTp7Tsc46qH/xv6UbAP76/BNxgkbkxO3sPNV22jx/ugOk2KNx8oLb+Rf8gCv1/DxEjSkeJzgtnqFrW3cNPx9P/YvCMt1QojNvW9c4usP/T2bcgSvcmZiBbv0reLFT1f9LcJb/AQ==</diagram><diagram id="Gs2cU2fz2AcDd8H0wgPk" name="Page-3">5Vpdc9o4FP01zLQPZPA3PFJCmrbJlimbbbMvHYFlWxNhMbIgSX/9Slj+kuRAUhyyu+Qh0rUkJJ17dM+V6TmT1cNHCtbJNQkh7tmD8KHnnPds27IGPv8nLI+5ZTQKckNMUSgbVYY5+gWlcSCtGxTCrNGQEYIZWjeNS5KmcMkaNkApuW82iwhufusaxFAzzJcA69bvKGRJbh3aQWW/hChOim+2/FH+ZAWKxnIlWQJCcl8zOdOeM6GEsLy0ephALDav2BdwcTH+edu//PL552IeRfH5/Oumnw928Zwu5RIoTNmLh/77rztsgyBYxdtpH2+9qz/sO9llsAV4I/drvAbLBHLbmGGQyZWzx2I7KdmkIRRDWj3nw32CGJzzHuLpPXcgbkvYCsvH2R1ky0RWAF1K7whEDaM45eUlXxKkoi0fBaXxFYzEEj1u2ULKEAdyLJsyIoaXE+bP4IOC8J7tsUrMuLNDsoKMPvJ+chQnkHsh/dwZyPp95TWOL21JzWNsVxqB9NS4HLtCgxckIM8Ax9LAmcaQIsBtX6/HH/m/GQYsInTVs33Mp/NhQXkpFqV3c0j5JvE2kwRkGcre621Mlg7gHtXgxjt4DwB7QRgjqw7xHu2H235duO29XCwOSUKPCFSEMJ4QzMcUAzmhB4ehKxoxSu5g7cnQXji+30rMCvChid9d4Wj5CpC2DqQ1NABZdjw6kI4G5DVkIAQM6IybQcrJyWDKoeoM0yiC/nJpwjQMRgvu+TqmKxSGYh4Kj7tC0bUVFH0Dis6roug+geKAbyHmREQkPSkTOyOVGgw9Axym09HpCg1PQ+MbBKGuT2p7Cx8Q+1Er3/Ly4MyTtXOx1EFReSwqKZ/sj3ol72V7Rb3qt6sVHSOSMskTy249I9uRbMW+7iAw5NJWrpVQlpCYpABPK6t0CNHuBe7AN5Js6BLuJwUDNIZs3xHY6l59vqGW4zdcrG/pLuYZPKywUci1D9o212lyOzmLGUF8B8opqPHf9Z0zy/aaw+TbIXvWpbUyWDAMzrwmYVQi5DumDTWmFDzWmq1Fg6x92o4a7XzvyZmp7d1BI0nghXwG5t5Ws3MJUTFbEkUZZD2V2yXgL6e7/wK6t1D3d5lbRkKNvP7uYwi3nvh7PnnFTGrD5B9uD0GWlAHlNxm+l7nuPuZa/POaTLUUaWAPFS88lKWF71fc8c9Uxh+JpuqcFZq20a57XgU6r6bzP0WGMfskEgzxhTzNwAjK9Z1MkCaEol+cEABLnnaldTztSDVkgiblGXSldYYaSDcZ1FO+LAFrUdys8HiXE1Zn1xVYQDwjGdop1Fo2bZYlNdTIhmGUckSK2zix9U3c2zFrQ7nKITRJ0xWqvqJgXYO8cA2oqofL0UAdaaBOKAQMlqxTM8ObdfjU43OI4e7xARGxrBwnIrZo2b1u8Mxw2PSaQs0Xkj1fiqN8nhb3vMLzbcQBFVcStVOlO8E8PDDs7hXMlu8HTTVmuOjoMAxrhFIV7sFhWI2NQTcxWJuwe5D07T4GFyfRSY6CGvtvG+T/Nx4FZTJfLuW/yf1TJ8uBq0hw9dLtUO5rWqsr7qu3+03u62fS8Mn2bzZNtvRXRN/hghtuPr0h9d6lznOVzS8vXuo3lSahZ3cl9Pg5qWKivcf5DLagzLPeDlBdplmOSjFDmmW64O9MkFv6Bf+Mwv5ig7DgNmc4jCkQCZRA7N2lOD7tiQgYbPn+pJid+l2NowirwEA5ywBlZ69qLP3twHS1gKEAxB58AdEd+H+SzDW8tzkSyXi1+ulLHs+qHxA5038A</diagram></mxfile>