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.