Creating New Entities

Entities are defined as a data object that can be used by DIF. DFEntity is the interface used to interact with these objects (a subinterface of DFItem). While they are usually used to define a single database table, they could be used to define multiple tables. It is important to note that DFEntity only defines the 'structure' of the table. Data itself is handled via DFEntityDataProvider.

In general, there are two types of entities - structure entities and standard entities. The former ones can contain a structure field capable of storing chemical structures while the latter ones can only contain simple data such as text and numbers.

Creating both types of entities is simple when using helper methods in DFEntities class. The code below creates a new JChem Base structure entity with the name STRUCTURES and another standard entity with the name DATA. As you are writing to the schema, you will need to lock it. In groovy scripts you can use method withLock on DFLockable objects which accepts optional reason and the closure with the code which needs to be executed locked. Single parameterDFEnvironemntRW is passed to that closure. It should be noted that while these entities are created, they aren't promoted .

Please note, that the following script needs to run from the Schema and not from a Data Tree.

import com.im.commons.progress.*
import com.im.df.api.ddl.*
 
schema.lockable.withLock('create new entities') { env ->
    def structuresEntity = DFEntities.createJChemEntity(schema, 'STRUCTURES', env)
    def dataEntity = DFEntities.createStandardEntity(schema, 'DATA', env)
}

Next example shows more advanced scripting where it is possible to do more customisation. The script creates a new entity named New JChem Entity and adds a new Binary Field to the entity. Please note, that the following script needs to run from the Schema and not from a Data Tree.

import com.im.commons.progress.*
import com.im.df.api.capabilities.*
import com.im.df.api.util.*;
import com.im.df.api.ddl.*;
 
schema.lockable.withLock('create new jchem entity'){ env ->
    def Class[] req = [ JChemBaseEntityCapability.class ]
    def nt = DIFUtilities.findFirstAppropriateNewType(schema.getEntities().getNewTypes(), false, req, new Class[0]);
    nt.options.newDFItemNameSafe = 'New JChem Entity'
    // Now you can do more customization of "new type options" (means creation parameters like what you see in IJC UI when creating a new jchem entity)
    println "New type valid and ready for creating entity:" + nt.options.valid
    def newEntity = nt.create(env).iterator().next()
 
    req = [ DFFieldBinaryCapability.class ]
    nt = DIFUtilities.findFirstAppropriateNewType(newEntity.getFields().getNewTypes(), false, req, new Class[0]);
    nt.options.newDFItemNameSafe = 'New Binary Field'
    println "New type valid and ready for creating binary field:" + nt.options.valid
    def newBinField = nt.create(env).iterator().next()
 
}