Introduction to development with .NET API of JChem Base

JChem Class Library is a collection of .NET classes, which provides the functionality of handling JChem structure tables in relational database management systems (RDBMS-s) for .NET applications.

Contents

• Software Requirements
• JChem Base features and architecture
• Initializing the Database for Structure Handling
• What is Useful to Be Familiar With Before Starting the Development
• Accessing Structure Tables
• Demo applications
• Connecting to Databases

Software Requirements

In order to develop applications using JChem Class Library the following software need to be installed:

• .NET Framework 3.5 SP1 or later
• A relational database engine (RDBMS) that stores the structures in tables. The database server doesn't have to be installed on the same machine as the application if the computers are connected in a local network (Internet connection is also sufficient, but the speed of such system might be low).
  
  
• A .NET converted JDBC or ODBC Driver for the database engine The driver has to be installed on the same computer as the application. See FAQ for more details on JDBC and ODBC drivers.
  Note, some converted JDBC driver is stored in the package.
  
  

JChem Base features and architecture

The following table summarizes the technical details of JChem Base:

Technical details	Resulting features
It uses JDBC technology to store and retrieve structures in relational databases.	Most database engines (like Oracle, MSSQL, MySQL, PostgreSQL) can be used to store structures. Structural and other chemical or non-chemical data can be handled together. Tables can be joined. SQL statements can access structural data.
The software modules are supplied for chemical structure searching.	Fast and reliable search that can be built into custom systems. Web access to structure querying. Structure search and data manipulation can be handled by ASP scripts Structure search can be built into legacy databases.
Structure input/update/display by the Marvin Java Applets.	Convenient and interactive user interfaces for Java capable web browsers (recently all are)

Architecture: A typical interaction between a client and the database

1. Using a web browser, the user enters a structure into MarvinSketch.
2. A custom script for substructure/similarity searching is activated, which
   • Connects to a database through JDBC.
   • Searches in a table containing structures.
   • Creates a list containing the ID numbers of found structures
3. The script retrieves mixed structural and non-structural data by SQL SELECT statements, using the list of hits and tables or views in the database.
4. The script creates the page that displays the retrieved data in the client's browser using MarvinView.
5. The user manipulates the data ...

Please note that there are other possibilities for invoking substructure searching, which might better suit your demands.

Initializing the Database for Structure Handling

Before starting the development of a system that uses JChem to access structure tables in RDBMS-s, run JChemManager to initialize the database for structure handling:

• Create the JChemProperties table automatically by invoking JChemManager the first time. This table stores information on the database and the structure tables.
• Set advanced options, if necessary.
• Create a structure table.
• Import a structure file into the table (if needed).

See the documentation of JChemManager for more details.

What is Useful to Be Familiar With Before Starting the Development

• JChemManager
• Basic features of the selected database management system
• SQL
• JChem Class Library (described in this document and detailed in the API)
• Marvin (We suggest applying the Marvin Applets or JavaBeans for creating graphical interfaces)
• ASP, if you are developing a web application
• JDBC
• MDL Molfiles and SD files (SMILES/SMARTS might also be useful)

Accessing Structure Tables

Structure tables used by JChem reside in databases of RDBMS-s. See the administration guide for more details on managing these tables.

To access a structure table, a JDBC connection has to be built between the application and database. The tables can be handled by

• executing SQL statements (java.sql.Statement), or
• using objects from the JChem Class Library.

JChem's classes expect the following parameters:

• An initialized java.sql.Connection object, usually contained in a ConnectionHandler object.
• The name of the structure table. In the case of RDBMS-s supporting schemes, the owner of the table should also be specified followed by a dot before the actual name of the table (e.g.: cduser.structures). If you are unsure about the name, check the content of the JChemProperties table in the database.

Though structure tables can be manipulated without using JChem's classes, you must be careful not to harm the integrity of the database. Only custom data fields of jchem tables are allowed to be manipulated directly by SQL statements - otherwise the JChem API must be used.

Demo applications

It is suggested to setup and try one of the demos included in the JChem package before starting the development of a custom application powered by JChem.

Connecting to Databases

Java classes in JChem may use ConnectionHandler or the java.sql.Connection class passed as a parameter to connect to a database.

Examples for opening a connection using ConnectionHandler

ConnectionHandler conHandler = new ConnectionHandler();
conHandler.setUrl(url);
conHandler.setDriver(driver);
conHandler.setPropertyTable(propTableName);
conHandler.setLoginName(userName);
conHandler.setPassword(password);
try {
  conHandler.connect();
} catch ...

If parameters of the connection are saved in JChemManager then they can be reused from code.

ConnectionHandler ch = new ConnectionHandler();
Properties props = new SettingsHandler().getSettings();
if (!ch.loadValuesFromProperties(props)) {
  throw new IOException("Insufficient connection data.");
try {
  ch.connect();
} catch ...

Structure cache identification and registration

Cache identifiers are introduced in JChem 5.3.2 in order to better scale search and database performance and improve safe and efficient structure cache load. Caches - or more precisely, cache pools - are identified with a cache ID. All the caches get the same cache ID if they belong to the same cache pool. This way the cache ID identifies the cache pool or - what is equivalent to this - the JVM. By default all cache pools get a random cache ID (this ID can be modified in case of permanent caches - see #3).

In order to run a well performing search application, the cache ID must be registered before the first search. The registration process inserts a record into the cache registration database table. If an application hasn't been registered before the first search is performed, it tries to register itself automatically but it may fail if the database connection is used in a transaction.

Before closing your application (quitting the JVM) please always unregister your cache!
There is only one exception to this rule: if your cache is permanently registered you may restart your application and simply set the previously registered cache ID (see #3). No re-registration is needed in this case.

Types of cache registration: temporary and permanent

The registration of a temporarily registered cache may be deleted automatically after 1 day of inactivity (that is, no searches have been initiated by the cache pool in the last day). After deletion, the cache should be registered again. The default cache registration is temporary.

Permanent cache registrations do not expire and can be unregistered only via the API (#4, #5). Permanent registration needs a unique cache ID that can be set or can be given at registration (#2, #3). Please use permanent registration only if your application is continuously running (e.g. server applications).

Recommendations

• An unregistered cache always reloads its structure cache before every search, so it's recommended to register at the startup of the application!
• Registration should be done outside of a transaction.

Registration and unregistration of cache ID

CacheRegistrationUtil is designed to handle registration process. For registration operations a connected ConnectionHandler (ch in the examples) is needed in almost every case - except when setting a permanent cache ID (see #3).

• #1 - Registration without using a cache ID

  CacheRegistrationUtil cru = new CacheRegistrationUtil(ch);
  cru.registerCache();
  

  By default the registration will be temporary, using the default random cache ID. If a permanent cache ID (see #3) was set before, the registration will be permanent, using the given ID.

• #2 - Registration with a cache ID (can be used only for permanent caches)

  String identifier = "unique_cache_identifier";
  CacheRegistrationUtil cru = new CacheRegistrationUtil(ch);
  cru.registerPermanentCache(identifier);
  

  The last line has two effects:
  
  a) Changes the default cache ID to identifier.
  b) Registers identifier as permanent cache ID.

• #3 - Setting a permanent cache ID

  String identifier = "unique_cache_identifier";
  CacheRegistrationUtil.setPermanentCacheID(identifier);
  

  The second line changes the default cache ID to identifier and sets the cache registration type to permanent, so subsequent calls to registerCache() (see #1) will register the cache as permanent!

• #4 - Unregistering the cache without using a cache ID

  CacheRegistrationUtil cru = new CacheRegistrationUtil(ch);
  cru.unregisterCache();
  

  Unregisters the current cache's cache ID.

• #5 - Unregistering the cache using a cache ID

  String identifier = "unique_cache_identifier";
  CacheRegistrationUtil cru = new CacheRegistrationUtil(ch);
  cru.unregisterCache(identifier);
  

  Unregisters the given cache ID (temporary or permanent).