Rosette Server - Embedded allows you to run Rosette Server within your own Java application JVM. Your application uses the same binding API, including data model classes, as it would use to access Rosette Server as a web service, but all work is done in your application's process, so there is no overhead for network communications or data serialization.
Rosette Server can be consumed by multiple threads. You can configure its thread pool size according to your hardware such as number of CPU cores.
Installing Rosette Server - Embedded
On macOS and Linux systems, the install script will install Rosette Server - Embedded. On Windows, you will receive Rosette Server - Embedded as a zip archive file. Unpack the file in a convenient directory (installDirectory). You will need the resulting directory both to compile Java applications and to run them. You cannot use Docker with Rosette Server - Embedded.
Notice
installDirectory is the name of the directory you entered during installation/embedded. For example, if you selected rosette-workspace as the install location, installDirectory is rosette-workspace/embedded.
In addition to the main contents, you will receive a separate license file, named rosette-license.xml. Copy this file to installDirectory/config/rosapi in your installation.
Including Rosette Server - Embedded in Your Application
When you install Rosette Server - Embedded, the resulting installDirectory contains all of the runtime code and data needed to use Rosette in your application. installDirectory/lib contains the JAR files that you need to incorporate into your application's classpath. For example, if you use Apache Ant, you might write the following to incorporate the jar files in an ant path construct.
<property name='rosette.lib' location="${rosette.embedded.install}">
<path id="class.path">
<fileset dir="${rosette.lib}">
<include name="**/*.jar" />
</fileset>
</path>
Creating EmbeddedRosetteAPI Objects
To use Rosette Server - Embedded, you create an EmbeddedRosetteAPI object using com.basistech.rosette.localapi.EmbeddedRosetteAPI.Builder.
The builder requires you to specify the install directory, as follows:
AbstractRosetteAPI api = new EmbeddedRosetteAPI.Builder()
.installDirectory(Paths.get("/install_directory");
.build();
Note
Using the AbstractRosetteAPI class allows you to switch between RESTful and Embedded modes, including via dependency injection.
In addition to the install directory, the builder allows you to optionally supply two other directories:
-
config directory: configuration text files
The config directory contains text files that customize the behavior of Rosette. The installation includes a default set of these files in the config subdirectory of installation. It you don't call builder.configDirectory the builder will use that set.
-
cache directory: a work directory used by Rosette
If you do not call builder.cacheDirectory to specify this, Rosette will call java.nio.file.Files.createTempDirectory(java.lang.String, java.nio.file.attribute.FileAttribute<?>...) to create a temporary directory.
Once you have an EmbeddedRosetteAPI object, you call it to perform text analysis operations.
Calling the Rosette Server - Embedded API
Rosette Server - Embedded defines a series of endpoints; each endpoint performs a text analysis task. For example, the /entities endpoint tags the entities in a text. You specify an endpoint to the API by providing its path; /entities is an endpoint path. To invoke the API, you prepare a request object, and pass the endpoint path, the request object, and the Class of response that the endpoint returns to the EmbeddedRosetteAPI object. You receive, in return, a response object or an exception.
Most of the endpoints accept free text; these are the document endpoints. The other endpoints accept names, and are described later. All the document endpoints use a common class for their requests: com.basistech.rosette.apimodel.DocumentRequest. DocumentRequest is a generic class. The generic parameter is an option class, which is not used in simple cases. Here's a simple example:
DocumentRequest<? extends Options> request = new DocumentRequest.Builder<>()
.content("George Washington slept in Lincoln, Nebraska.")
.build();
EntitiesResponse response =
api.perform(AbstractRosetteAPI.ENTITIES_SERVICE_PATH,
request, EntitiesResponse.class);
The Names Endpoints
The endpoints, /name-translation, /name-similarity, and /name-deduplication, work with the names of people, places, and organizations. These endpoints have their own request and response classes that you can read about in the javadoc.
Simple and AnnotatedText Responses
The Rosette API defines two data models for results: simple and annotated text. The simple model consists of a data structure for each endpoint that contains the essential results of the operation. For example, for entities, the simple response contains a list of EntityMention objects, each of which contains the basic facts about a mention of an entity in document.
In contrast, the Annotated Data Model provides a comprehensive data model for text analytics. When you request an AnnotatedText object as the response type, you get the full results of the text analytic operations that make up the endpoint.
Rosette Server - Embedded Examples
Rosette Server - Embedded includes an examples directory, containing examples for each of the endpoints.
Prerequisites
Notice
installDirectory is the name of the directory you entered during installation/embedded. For example, if you selected rosette-workspace as the install location, installDirectory is rosette-workspace/embedded.
Ant (http://ant.apache.org/manual/install.html) must be installed and operational.
-
The roots directory is symlink'd to ROSAPI_ROOTS. This is done automatically for macOS and Linux users in the install.
Windows:
The license file rosette-licence.xml is installed in config/rosapi
Running examples
cd to examples/endpoints
ant run
Using Maven with Rosette Server - Embedded
The Rosette - Server Embedded examples/endpoints directory includes a pom.xml file listing the dependencies for running the embedded examples. If you are using Maven in your development environment, you can use the included pom file to build the examples.
mvn verify
The above command will build all the examples and run the CategoriesExample. Edit the file to add the examples you'd like to run.