This document is a subsection of the Installation Guide.
This section provides requirements, instructions, and troubleshooting information for installing a LexEVS Local Runtime.
LexEVS has been tested with the operating systems and hardware specified in the LexEVS 5.x Supported Platforms]. While LexEVS is expected to run on many variations of hardware and software similar to the test platforms, results cannot be guaranteed. Before you begin you should check to make sure that your platform will support the software. |
Once you have completed the prerequisite software install, the Local Runtime environment install steps, and the verification test as described in this guide then you should be ready to start programming using the API to meet the needs of your application. Not counting prerequisite software products the installation and verification should not take more than 60 minutes.
Step |
Action |
|||
---|---|---|---|---|
1. Download the latest version of the Local Runtime GUI install package from the right. The location you have chosen to save this on your computer will be referred to as the
|
||||
2. Using a file explorer, navigate to the
Then enter the command to begin the installation wizard:
...where
|
|
|||
3. Click the OK button to begin the installation.
|
|
|||
4. After the initial welcome screen, the release notes for the LexEVS distribution are displayed. Once you have read through the release notes click the Next button. |
|
|||
5. Review the license agreement of the LexEVS software. Select "I accept the terms of this license agreement." and click Next. |
|
|||
6. Enter the path where you would like the LexEVS software installed. This will be referred to as
Click the Next button.
|
|
|||
7. Select the components to be installed. The components "Product Information" and "Runtime and Administration Toolkit" are required and cannot be unchecked. The remaining components are optional. Clicking on individual components will display a description of that component. |
|
|||
8. Once all the components have been installed, a Finished dialog box will be displayed. Click Next. |
|
|||
9. The last step of the installation wizard provides the ability to generate a command line installation configuration XML file that can be used on other servers. This installation script can be used to install LexEVS without the wizard that you just went through. If you want to generate this file then click the Generate an automatic installation script button. This will have no effect on the current installation. For more information look at the optional #Downloading and Installing the LexEVS Local Runtime. |
|
This section describes the location and organization of installation materials. Following installation, many of the following hierarchy of files and directories will be available (some features are optionally installable):
(As located in the LexEVS installation root directory)
Directory |
Description of Content |
|
---|---|---|
/admin |
Installed by default. This directory provides a centralized point for command line scripts that can be executed to perform administrative functions such as the loading, activation/deactivation, and removal of vocabulary resources. |
|
/doc |
Optionally installed. This directory provides documentation related to LexEVS services, configuration, and execution. This guide is distributed in the /doc top-level directory. |
|
/doc/javadoc |
This directory provides documentation for model classes and public interfaces available to LexEVS programmers. Also included with each object representation is a UML-based model diagram that shows the object, its attributes and operations, and immediately linked objects. The diagrams work to provide clickable navigation through the javadoc materials |
|
/examples |
Optionally installed. This directory provides a small number of example programs. |
|
/examples/resources |
Contains sample vocabulary content for reference by the example programs; use the /examples/LoadSampleData command-line script to load for example code use or use one of the loaders in the /admin folder to load other content. |
|
/gui |
Optionally installed. This folder contains programs and supporting files to launch the LexEVS Graphical User Interface (GUI). The GUI provides convenient centralized access to administrative functions as well as support to test and exercise most of the LexEVS API. |
|
/logs |
Default location for log files, which can be modified by the |
|
/resources |
Installed by default. This directory contains resources referenced and written directly by the LexEVS runtime. It should, in general, be considered off-limits to modify or remove the content of this directory without specific guidance and reason to do so. Files typically stored to this location include the vocabulary registry (tracking certain metadata for installed content) and indexes used to facilitate query over the installed content. |
|
/runtime |
Installed by default. This directory contains a Java archive (.jar) file containing the combined object code of the LexEVS runtime, LexEVS administrative interfaces, and any additional code they are dependent on. All required code for execution of LexEVS administrative and runtime services is installed to this directory.
|
|
/runtime/sqldrivers |
The JDBC drivers used to connect to database repositories are not included in the lbRuntime.jar. Instead, the runtime scans this directory for the drivers to include. This can be overridden by path settings in the lbconfig.props file.
For example, the Oracle database is supported by the runtime environment. However, the drivers are not redistributed with the LexEVS software. To run against Oracle, an administrator would add a jar with the appropriate JDBC driver to this directory and then reference it in the lbconfig.props settings. MySQL, the main test base for LexEVS, also requires a restricted license driver. It's driver can be downloaded here: mysql-connector-java-5.1.6. |
|
/runtime-components |
Optionally installed. Due to license considerations for additional materials (as described by the license.pdf and license.txt files in the install directory), the cumulative runtime provided in the lbRuntime.jar is not redistributable.
|
|
/runtime- |
This subdirectory includes all 3rd party code redistributed with the LexEVS runtime, along with respective license agreements. |
|
/source |
Optionally installed. This directory provides central accessibility to Java source for all code developed for the LexEVS project. |
|
/test |
Optionally installed. This directory provides an automated test bucket that can be used by System Administrators to verify node installation. Note that the /runtime/config/lbconfig.props file must still be configured for database access prior to invoking the test bucket. |
|
/uninstaller |
Contains an executable jar that can be invoked by an administrator to uninstall files originally introduced by the LexEVS installation. |
The LexEVS Local Runtime can be configured to work with many different databases, however, the recommended databases are MySQL or PostgreSQL as noted in LexEVS 5.x Prerequisite Software Supported. Following installation of a database of your choice you should follow these steps in order. The remaining text in this section is meant to help facilitate these steps.
It is considered beyond the scope of these install instructions to address database setup and administration. However, proper database configuration is critical to the performance and long-term health of the LexEVS environment. |
At a minimum you should consider changing these properties controlling the behavior of the MySQL database server. These properties are usually located in the file {MYSQL_HOME}/my.ini.
Property Name |
Description |
---|---|
innodb_flush_log_at_trx_commit |
Flush the transaction logs at each commit. |
innodb_additional_mem_pool_size |
Additional memory pool that is used by InnoDB to store metadata information. |
innodb_buffer_pool_size |
Buffer pool used to cache both indexes and row data. |
tmp_table_size |
Maximum size for internal (in-memory) temporary tables. |
query_cache_size |
Query cache is used to cache SELECT results and later return them without actually executing the same query once again. |
sort_buffer_size |
This buffer is allocated when MySQL needs to rebuild the index in REPAIR, OPTIMZE, ALTER table statements as well as in LOAD DATA INFILE into an empty table. |
MySQL can be passed a JDBC option for the Windows local environment that may improve perfomance 30 to 50%. |
Try the following values in the lbconfig.props file for the DB_URL. This uses Windows Named Pipe function and avoids use of the TCP/IP protocol. It only works when connecting with a local iteration of the MySQL database on Windows.
DB_URL=jdbc:mysql:///<dbname>?socketFactory=com.mysql.jdbc.NamedPipeSocketFactory |
There are some commands that we have found useful in this environment. You can investigate this database software more at the MySQL web site.
If you have root or administrator access to your server you can change the password for the root user ID if you have forgotten or lost it.
mysqladmin -u root password \{mypassword\} |
...where mypassword
is your new password
Creating a database within the software can be done via the command line. The software does not come, by default, with GUI administration. That command might look like this:
mysqladmin -u root -p create \{DBNAME\} |
...where DBNAME
is the name of your database needed for LexEVS to store data in. You will be prompted for your password before the database is created.
The following file contains properties controlling the behavior of the PostgreSQL database server:
PostgreSQL_HOME_DIRECTORY}/posgresql.conf |
Property Name |
Description |
---|---|
shared_buffers |
Number of shared buffers. |
work_mem |
The amount of memory in kilobytes allocated to working memory |
maintenance_work_mem |
The amount of memory in kilobytes allocated to maintenance working memory. |
enable_seqscan |
We set the |
The next step is to configure LexEVS. This is wrapped up in editing one file, {LEXEVS_HOME}/resources/config/lbconfig.props.
This file contains properties controlling the behavior of the LexEVS Local Runtime.
The lbconfig.props file has the latest documentation embedded inside of it. lbconfig.props should be considered authoritative if there is a difference between the documentation written here and that contained in lbconfig.props. |
Below you will find an expanded overview of the options in this file. Options in BOLD must be modified so that LexEVS can properly use your database. They are also noted as required. There are many other options that you can change for performance reasons or alternative deployment scenarios, but you probably don't need to change them in a standard LexEVS installation. Some options can not be changed after you load terminologies into LexEVS. Now would be a good time to read about what is available to you.
A single back slash '\' is not valid within the lbconfig.props file for file or directory paths (except within JDBC connection strings). When constructing file or directory paths you must use either a forward slash '/ or two backward slashes ' |
Property Name |
Description |
|
---|---|---|
DB_URL |
Required: The address of your database server. This will include the host name or IP address followed by the name of the database that you created to store LexEVS data. For example:
...where |
|
DB_PREFIX |
Required for Oracle databases: The prefix to use on all tables or databases that LexEVS creates. |
|
DB_PARAM |
Optional variable for passing extra database parameters. These will be appended to the end of the database connection string. |
|
DB_DRIVER |
Required: The Java class name that represents the driver that you wish to use with your database. |
|
DB_USER |
Required: The database username. This account must have permission to add and remove tables, indexes, etc inside of this database. |
|
DB_PASSWORD |
Required: The password for the database username. |
|
LG_CONFIG_FILE |
This is not actually a variable that you would set within this file. It is documented here for clarity of other variables that depend on this variable. |
|
LG_BASE_PATH |
This variable is the path that will be used to resolve any other relative (or unqualified) paths in the lbconfig.props file. |
|
JAR_FILE_LOCATION |
The path of the folder that contains your SQL drivers and LexEVS extensions (if you have any). |
|
REGISTRY_FILE |
The location of the file that will store information about all loaded terminologies. |
|
INDEX_LOCATION |
The folder where all LexEVS generated indexes will be stored. This folder can potentially be large (100+ GB) - depending on the terminologies loaded. |
|
MAX_CONNECTIONS_PER_DB |
LexEVS maintains a pool of connections to each database that it connects to. This sets the limit on the number of connections that will be opened. You may want to set this to a higher value - 20 or so (depending on expected user load) |
|
CACHE_SIZE |
LexEVS maintains an internal cache of some information that it needs to query from the database to resolve queries. This controls the size of that cache. This cache does not hold entire user queries. |
|
ITERATOR_IDLE_TIME |
The length of time to allow an unused (and unclosed) iterator to stay valid before it is closed (and its resources freed) by the system. |
|
MAX_RESULT_SIZE |
This controls the maximum number of results that a user can resolve at one time for the CodedNodeSets and CodedNodeGraphs. |
|
LUCENE_MAX_CLAUSE_COUNT |
The number of boolean 'clauses' Lucene will attempt to create for wildcard or Regular Expression queries. For very general queries on large ontologies, this will need to be set high. |
|
LOG_FILE_LOCATION |
The path where LexEVS log files will be written. |
|
API_LOG_ENABLED |
Setting API call logging to 'true' will cause every method call to be printed to the log file. |
|
SQL_LOG_ENABLED |
Setting SQL logging to 'true' will cause every sql statement executed to be printed to the log file. |
|
DEBUG_ENABLE |
Setting debug to 'true' will give you more verbose logging information to debug problems. This should normally be set to 'false' since debug logging causes a negative performance impact. |
|
LOG_CHANGE |
Indicates when a new log file should be started. This can be set to 'monthly', 'weekly' or 'daily'. |
|
ERASE_LOGS_AFTER |
If |
|
EMAIL_ERRORS |
Used to enable or disable e-mail notification of system errors and warnings. If you set this to 'true', you must set |
|
SMTP_SERVER |
The SMTP server to use to send errors over e-mail. |
|
EMAIL_TO |
A comma separated list of e-mail address to set failure and warning notifications to. |
This Local Runtime installation provides a test suite to verify the environment. Before running these tests the Local Runtime and databases must already be configured.
Step |
Action |
||
---|---|---|---|
1. In a command prompt window change to the test directory:
...where
|
|
||
2. Use a file explorer to navigate into the directory that contains the test report. The report directory is placed in |
|
||
3. Launch the report into the default browser by double-clicking on the |
|
||
4. Review the test results. You should expect no failures or errors if the configuration of the Local Runtime and the databases is correct. If there are errors refer to the troubleshooting section. |
|
If all the tests pass then you have successfully installed the LexEVS Local Runtime. Congratulations!
LEXEVS_HOME
, you might get errors from the underlying database during runtime. It it highly recommended that you do not use a space in the path.lbconfig.props
, registry.xml and the entire lbIndex directory in the resources directory. Note that the names of those last two files can be altered by variables in the lbconfig.props file.registry.xml
and metadata.xml
files by hand.lbconfig.props
.Loading in single database mode can eliminate this problem. |
{LEXEVS_HOME}/runtime/sqlDrivers/ |