Locks

Most DIF write methods use locking. This effectively means that the object being written to is 'locked' so that no other changes can be made while your method runs. Before the method is called, you must obtain the lock for that item, put it in the DFEnvironmentRW (see below), and then pass the environment to the data modification method. These are controlled via the interface DFLockable . The lockable for an item provides only a single DFLock , at the same time.

It is important to determine which area of the DIF to lock for the method at hand. The various

methods are discussed on the DFLockable page, separating out the DDL or DML items that can be used to lock schemas, entity data providers, user-owned items, and so on. The most important lock is the global DDL lock for shared items, which is used when altering schema, entities, etc. Beyond this is the global DDL lock for user specific items (DFView, DFQuery, DFList).

Environments

In DIF methods, everything is executed in the same thread, with no return until the operation is complete. This poses a problem for long-running process, and potential occupation of the threads necessary for updating of the GUI. In order to provide feedback, and move long-running methods to the background, environments were introduced. These can pass common parameters to methods, as well as provide feedback on the background process. Currently the two functions of an environment are a holder for feedback (via DFFeedback ) and a lock. If the method does require a lock, then a simple read-only environment is needed (with no locks). In this case the RO environment is a holder for feedback on the method running.

There are three types of methods:

• No modifications : Those performing queries, reading a file, performing calculations, etc. These methods use the interface DFEnvironmentRO (read only). This allows for long running methods to provide notifications about progress and errors.

• Modifying methods : If a method requires writing (editing an infrastructure or altering data), then the method requires a read-write environment, controlled via the interface (DFEnvironmentRW ). Because no method is asynchronous, the appropriate part of the DIF (be it data tree, entity, or entity data provider) must be 'locked' in order to prevent other changes from happening at the same time. This lock is created separately and then passed into the DFEnvironmentRW.

• Fast methods : Methods which happen very fast do not require an environment.

Environments can be created using the EnvUtils class of methods. Feedback can be passed back from either type of environment using the

methods. It is worth noting that DFEnvironmentRW is a subinterface of DFEnvironmentRO, and a RW environment can be created from an existing RO environment via the method

DDL Capabilities

Capabilities help to extend the basic DFItems. For example, DFField could be a column in a file, or in a database. Capabilities are a way to differentiate the two. It can also further define datatypes once it is determined that the DFField belongs to a database, leading to capabilities such as DFFieldStructureCapability. These are important for defining new objects. Capabilities can have properties (getSomething/setSomething), but property change support is implemented on the level of the master/owner object DFItem. The interface DFCapability lists all known subinterfaces (capabilities).

New Types

All DFItems belong to each other through the DFContainer interface. This is a simple hierarchy, in which the container has lists of types of the items it contains (eg the DFSchema container has lists of the potential new types of DFDataTree, DFEntity, and DFRelationship). The parent Items will have a container fetching method, such as

in the DFSchema interface. This method will return the entities container. It is through the container interface that new objects of type are created, via

DFNewType is the object that can create the new item, based on the context that the NewType (and thus container) came from. There are several options within DFNewType for each kind of DFItem - thus, knowing the DFCapability needed for the desired item is necessary to create the new object. This simplifies the process as the list of newTypes is extensive. NewTypes themselves can either create a new object, or a newType which takes an existing database artiface and promotes it to a recognizable item in IJC ("promoting" an item in the GUI). The API for DFNewType provides further details on how to use NewType to get the capabilities for the object/container in question.

Creating new DFItems via DFNewTypes is overtly complicated. Since IJC version 5.8, there are now utility methods that simplify the creation of certain DFItems. DFFields is an excellent example, now containing the

and more. This removes the need to search for NewTypes, or be concerned about the container. Not all field types are currently supported (chemical terms and calculated fields are not done yet), but are being developed.

Javadoc

Instant JChem is composed of many modules (currently approximately 45), but many of these contain only 3rd party libraries. The number of modules that need to be used for extension is relatively small. JavaDocs for these key modules is being prepared. Not all are currently ready. The most important module is the DIF module that defines the lowest tier mentioned above.
Please note that the stability differs for different parts of these APIs. We try to indicate this in the JavaDocs.

• IJCBase

• Progress and Background Tasks Support

• Commons - Database

• Commons - User Interface

• IJC Services API

• DIF API

• DIF Core implementation

• IJC Core module

• Conditional Formatting

• Forms Model