Merge pull request #149 from rosette-api/suppo-1256-readme

Suppo 1256 readme

Author: seth-mg

DEVELOPER.md

@@ -0,0 +1,28 @@
+## Developer Notes
+
+#### Building and Releasing
+To be updated..
+
+
+#### Internal Releasing
+TBD..
+
+#### Old Stuff
+[Docker](examples/docker) bits for running examples.  Maybe just remove?
+
+A duplicate copy of the examples docker notes is below...
+
+Docker files can be found [here](https://github.com/rosette-api/java/tree/master/examples/docker)
+
+To simplify the running of the Java examples, the Dockerfile will build an image and install the rosette-api library from the *published source*.
+
+Build the docker image, e.g. `docker build --rm -t basistech/java:1.1 .`
+
+Run an example as `docker run --rm -e API_KEY=api-key -v "path-to-java-dir:/source" basistech/java:1.1`
+
+To test against a specific source file, add `-e FILENAME=filename` before the `-v`.
+To test against an alternate url, add `-e ALT_URL=alternate_url`.
+
+#### TODOs
+...
+

README.md

@@ -1,11 +1,23 @@
+<a href="https://www.rosette.com"><img src="https://s3.amazonaws.com/styleguide.basistech.com/logos/rosette-logo.png" width="181" height="47" /></a>
+
+---
+
 [![Build Status](https://travis-ci.org/rosette-api/java.svg?branch=master)](https://travis-ci.org/rosette-api/java)
-[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.basistech.rosette/rosette-api-java-binding/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.basistech.rosette/rosette-api-java-binding)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.basistech.rosette/rosette-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.basistech.rosette/rosette-api-java-binding)
 
-# Java client binding for Rosette API #
+## Rosette API
+The Rosette Text Analytics Platform uses natural language processing, statistical modeling, and machine learning to
+analyze unstructured and semi-structured text across 364 language-encoding-script combinations, revealing valuable
+information and actionable data. Rosette provides endpoints for extracting entities and relationships, translating and
+comparing the similarity of names, categorizing and adding linguistic tags to text and more.
 
-## Installation ##
-If you use Maven, include this dependency in your `pom.xml`:
+## Rosette API Access
+- Rosette Cloud [Sign Up](https://developer.rosette.com/signup)
+- Rosette Enterprise [Evaluation](https://www.rosette.com/product-eval/)
 
+## Quick Start
+
+#### Maven
 ```xml
 <dependency>
     <groupId>com.basistech.rosette</groupId>
@@ -14,35 +26,26 @@ If you use Maven, include this dependency in your `pom.xml`:
 </dependency>
 ```
 
-where `${rosette.api.java.binding.version}` is the [latest version available from Maven Central](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.basistech.rosette%22%20AND%20a%3A%22rosette-api%22).
-
-The version will change as new versions of the binding are released. Note that versions of the form `x.y.Nxx`, where `N` is greater than 100, are internal testing versions; do not use them without consultation with Basis Technology Corp.
-
-If the version you are using is not the latest from Maven Central. Please check for its
-[**compatibilty with api.rosette.com**](https://developer.rosette.com/features-and-functions?java).
-If you have an on-premise version of Rosette API server, please contact support for binding
-compatibility with your installation.
-
-The source code on the master branch is the current state of development; it is not recommended for general use.
-If you prefer to build from source, please use an appropriate release tag.
-
-## Basic Usage ##
-To check out more examples, see [examples](examples/src/main/java/com/basistech/rosette/examples)
-
-## API Documentation ##
-Check out the [documentation](http://rosette-api.github.io/java)
+Set `${rosette.api.java.binding.version}` in the `<properties>` block.  The latest version available is displayed
+in the Maven Central badge at the top of this page.
 
-## Release Notes
-See the [Wiki](https://github.com/rosette-api/java/wiki/Release-Notes).
+#### Test Releases
+Versions, of the form `x.y.z`, where `z` is greater than or equal to `100`, are internal testing versions.  Do not use
+them without consultation with Basis Technology Corp.
 
-## Docker ##
-A Docker image for running the examples against the compiled source library is available on Docker Hub.
+#### Examples
+View small example programs for each Rosette endpoint in the
+[examples](examples/src/main/java/com/basistech/rosette/examples) directory.
 
-Command: `docker run -e API_KEY=api-key -v "<binding root directory>:/source" rosetteapi/docker-java`
+#### Documentation & Support
+- [Binding API](https://rosette-api.github.io/java/)
+- [Rosette Platform API](https://developer.rosette.com/features-and-functions)
+- [Binding Release Notes](https://github.com/rosette-api/java/wiki/Release-Notes)
+- [Rosette Platform Release Notes](https://support.rosette.com/hc/en-us/articles/360018354971-Release-Notes)
+- [Binding/Rosette Platform Compatibility](https://developer.rosette.com/features-and-functions?java#)
+- [Support](https://support.rosette.com)
+- [Binding License: Apache 2.0](LICENSE.txt)
 
-Additional environment settings:
-`-e ALT_URL=<alternative URL>`
-`-e FILENAME=<single filename>`
+## Binding Developer Information
+If you are modifying the binding code, please refer to the [developer README](DEVELOPER.md) file.
 
-## Additional Information ##
-For more, visit [Rosette API site](https://developer.rosette.com)

examples/src/main/java/com/basistech/rosette/examples/README.md

@@ -1,37 +1,17 @@
-Rosette API Java Examples
-=========================
+## Endpoint Examples
+Each example file demonstrates one of the capabilities of the Rosette Platform.
 
-Each example class can be run independently.
+Here are some methods for running the examples. Each example will also accept an optional `-Drosette.api.altUrl`
+parameter for overriding the default URL.
 
-If you use Maven, everything should have been setup and you can start running the examples using `mvn exec:java`.
-Otherwise you can compile and run these examples by hand:
+A note on prerequisites. Rosette API only supports TLS 1.2 so ensure your toolchain also supports it.
 
-- make sure you have JRE 1.7+, verify by `java -version`
-- download <TODO: nexus url>
-- `cd src/main/java/com/basistech/rosette/examples`
-- `javac -cp .:<path-to-rosette-api-jar-file> *.java`
-- `java -cp .:<path-to-rosette-api-jar-file> -Drosette.api.key=<your-api-key> com.basistech.rosette.examples.<XyzExample>`
- 
-| File Name                                   | Description
-| -------------                               |------------- 
-| CategoriesExample.java                      | Gets the category of a document at a URL
-| EntitiesExample.java                        | Extracts entities
-| InfoExample.java                            | Gets information about Rosette API
-| LanguageExample.java                        | Detects language
-| MorphologyCompleteExample.java              | Gets the complete morphological analysis
-| MorphologyCompoundComponentsExample.java    | Gets the de-compounded words
-| MorphologyHanReadingsExample.java           | Gets the Chinese/Han readings
-| MorphologyLemmasExample.java                | Gets the lemmas
-| MorphologyPartsOfSpeechExample.java         | Gets the part-of-speech tags
-| NameDeduplicationExample.java               | Gets a list of cluster IDs given a list of names
-| NameSimilarityExample.java                  | Matches two names and produces a match score
-| NameTranslationExample.java                 | Translates a name
-| PingExample.java                            | Pings the Rosette API to check for availability
-| SemanticVectorsExample.java                 | Gets the text embedding
-| SentencesExample.java                       | Gets the sentences
-| SentimentExample.java                       | Gets the sentiment of a local file
-| SimilarTermsExample.java                    | Gets the list of similar terms
-| SyntaxDependenciesExample.java              | Gets syntactical dependencies
-| TokenExample.java                           | Gets the tokens
-| TopicsExample.java                          | Gets topics
-| TransliterationExample.java                 | Gets transliteration
+#### Running from Local Source
+
+```
+git clone [email protected]:rosette-api/java.git
+cd java
+mvn compile
+cd examples
+mvn exec:java -Dexec.mainClass="com.basistech.rosette.examples.PingExample" -Drosette.api.key=$API_KEY
+```