Get our hibernate org.hibernate.criterion.Restrictions proxy object that will help you produce criterias.

Returns

• This function returns an instance of cborm.models.criterion.Restrictions

Examples

// Get an instance of the restrictions
var restrictions = ormService.getRestrictions();

// Restrictions used with criteria queries
var r = ormService.getRestrictions();
var users = ormService.newCriteria("User")
    .or( r.eq("lastName","majano"), r.gt("createDate", now()) )
    .list();

These methods allows you to tap into the Criteria Queries API so you can do fluent and functional queries with your ORM objects.

These methods allow you to create entities and populate them from external data like structures, json, xml, queries and much more.

These methods allow you to do counting on entities with or without filtering.

The Base ORM Service has a ton of methods to assist you with your ORM needs. We have compiled them under this section under several different categories:

• Criteria Queries

• Creation - Population

• Counters

• Deleting Entities

• Entity Convenience

• Finders

• Getters

• ORM Session

• Querying

• Saving

• Utility

Like always, you can find the latest API Docs in the link below:

Get a brand new criteria builder object to do criteria queries with (See ORM:CriteriaBuilder)

Returns

• This function returns coldbox.system.orm.hibernate.CriteriaBuilder

Arguments

Examples

var users = ORMService.newCriteria( entityName="User" )
    .gt( "age", ormService.idCast( 30 ) )
    .isTrue( "isActive" )
    .list( max=30, offset=10, sortOrder="lname" );

Get a new entity object by entity name. You can also pass in a structure called properties that will be used to populate the new entity with or you can use optional named parameters to call setters within the new entity to have shorthand population.

Returns

• This function returns the newly created entity

Arguments

Examples

// return empty post entity
var post = ormService.new("Post");
var user = ormService.new(entityName="User",properties={firstName="Luis", lastName="Majano", age="32", awesome=true});
var user = ormService.new("User",{fname="Luis",lname="Majano",cool=false,awesome=true});

Populate an entity with a structure of name-value pairs. Make sure the names of the properties match the keys in the structure.

Returns

• This function returns the populated object

Arguments

INFO With composeRelationships=true, you can populate one-to-many, many-to-one, many-to-many, and one-to-one relationships from property values in the memento. For 'many-to-one' and 'one-to-one' relationships, the value of the property in the memento should be a single value of the primary key of the target entity to be loaded. For 'one-to-many' and 'many-to-many' relationships, the value of the property in the memento should a comma-delimited list or array of the primary keys of the target entities to be loaded.

Examples

var user = ormService.populate( ormService.new("User"), data );

// populate with includes only
var user = ormService.populate( ormService.new("User"), data, "fname,lname,email" );

//populate with excludes
var user = ormService.populate(target=ormService.new("User"),memento=data,exclude="id,setup,total" );

// populate with null values when value is empty string
var user = ormService.populate(target=ormService.new("User"),memento=data,nullEmptyInclude="lastName,dateOfBirth" );

// populate many-to-one relationship
var data = {
    firstName = "Luis",
    role = 1 // "role" is the name of the many-to-one relational property, and one is the key value
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the role relationship will be composed, and the value will be set to the appropriate instance of the Role model

// populate one-to-many relationship
var data = {
    firstName = "Luis",
    favColors = "1,2,3" ( or [1,2,3] ) // favColors is the name of the one-to-many relational property, and 1, 2 and 3 are key values of favColor models
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the favColors property will be set to an array of favColor entities

// only compose some relationships
var data = {
    firstName = "Luis",
    role = 1,
    favColors = [ 1, 3, 19 ]
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true, exclude="favColors" );
// in this example, "role" will be composed, but "favColors" will be excluded

Return the count of instances in the DB for the given entity name. You can also pass an optional where statement that can filter the count. Ex: count('User','age > 40 AND name="joe"'). You can even use named or positional parameters with this method: Ex: count('User','age > ? AND name = ?',[40,"joe"])

Returns

• This function returns numeric

Arguments

Examples

Returns the count by passing name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: countWhere(entityName="User",age="20");

Returns

• This function returns numeric

Arguments

Examples

These methods allow you to delete one or more entities in cascade style or bulk styles.

Populate an entity with an XML packet. Make sure the names of the elements match the keys in the structure.

Returns

• This function returns the populated object

Arguments

Examples

var user = ormService.populateFromXML( ormService.new("User"), xml, "User");

Checks if the given entityName and id exists in the database, this method does not load the entity into session. A very useful approach to check for data existence.

Returns

• This function returns boolean

Arguments

Examples

Delete an entity using safe transactions. The entity argument can be a single entity or an array of entities. You can optionally flush the session also after committing.

Returns

• This function returns void

Arguments

Examples

var post = ormService.get(1);
ormService.delete( post );

// Delete a flush immediately
ormService.delete( post, true );

Populate an entity with a JSON structure packet. Make sure the names of the properties match the keys in the structure.

Returns

• This function returns the populated object

Arguments

Examples

var user = ormService.populateFromJSON( ormService.new("User"), jsonString );

Deletes all the entity records found in the database in a transaction safe matter and returns the number of records removed

Returns

• This function returns numeric

Arguments

Examples

Delete using an entity name and an incoming id, you can also flush the session if needed. The ID can be a single ID or an array of ID's to batch delete using hibernate DLM style deletes. The function also returns the number of records deleted.

Returns

• This function returns numeric

Arguments

Examples

These collection of methods will give you information about the currently loaded entity or the entity class itself.

Deletes entities by using name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: deleteWhere(entityName="User",age="4",isActive=true);

Returns

• This function returns numeric

Examples

ormService.deleteWhere(entityName="User", isActive=true, age=10);
ormService.deleteWhere(entityName="Account", id="40");
ormService.deleteWhere(entityName="Book", isReleased=true, author="Luis Majano");

Populate an entity with a query object. Make sure the names of the columns match the keys in the object.

Returns

• This function returns the populated object

Arguments

Examples

var user = ormService.populateFromQuery( ormService.new( "User" ), ormService.list( "User", { id=4 } ) );

Delete by using an HQL query and iterating via the results. It is not performing a delete query but is a select query that should retrieve objects to remove

Returns

• This function returns void

Arguments

Examples

// delete all blog posts
ormService.deleteByQuery("from Post");
// delete query with positional parameters
ormService.deleteByQuery("from Post as b where b.author=? and b.isActive = :active",['Luis Majano',false]);

// Use query options
var query = "from User as u where u.isActive=false order by u.creationDate desc"; 
// first 20 stale inactive users 
ormService.deleteByQuery(query=query,max=20); 
// 20 posts starting from my 15th entry
ormService.deleteByQuery(query=query,max=20,offset=15,flush=true);

// examples with named parameters
ormService.deleteByQuery("from Post as p where p.author=:author", {author='Luis Majano'})

Get an array of property names that that have been changed from the original loaded session state.

Returns

• An array of property names

Arguments

Examples

if( ormService.isDirty( entity ) ){
    // The values have been modified
    log.debug( "entity values modified", ormService.getDirtyPropertyNames( entity ) );
}

Returns the entity name from a given entity object via session lookup or if new object via metadata lookup

Returns

• This function returns string

Arguments

Examples

var name = ORMService.getEntityGivenName( entity );

Returns the key (id field) of a given entity, either simple or composite keys.

• If the key is a simple pk then it will return a string, if it is a composite key then it returns an array.

• If the key cannot be identified then a blank string is returned.

Returns

• This function returns any

Arguments

Examples

This method will return to you the hibernate's metadata for a specific entity.

Returns

• The Hibernate Java ClassMetadata Object ()

Arguments

Examples

Returns the table name of the passed in entity

Returns

• This function returns string

Arguments

Examples

var persistedTable = ormService.getTableName( "Category" );

Get the unique identifier value for the passed in entity, or null if the instance is not in session

Returns

• This function returns any

Arguments

Examples

var pkValue = ormService.getKeyValue( "User" );

Returns the persisted Property Names of the entity in array format

Returns

• This function returns array

Arguments

Examples

var properties = ormService.getPropertyNames("User");

Verifies if the passed in entity has dirty values or not since loaded from the database.

Returns

• This function returns true if the entity values have been changed since loaded into the hibernate session, else false

Arguments

Examples

if( ormService.isDirty( entity ) ){
    // The values have been modified
    log.debug( "entity values modified", ormService.getDirtyPropertyNames( entity ) );
}

Finders are convenience methods that will help you find a single entity or a collection of entities by using criterias. If you want to use primary keys, then use the getters.

Finds and returns the first result for the given query or null if no entity was found. You can either use the query and params combination or send in an example entity to find.

Returns

• This function returns any

Arguments

Examples

// My First Post
ormService.findIt("from Post as p where p.author='Luis Majano'");
// With positional parameters
ormService.findIt("from Post as p where p.author=?", ["Luis Majano"]);
// with a named parameter (since 0.5)
ormService.findIt("from Post as p where p.author=:author and p.isActive=:active", { author="Luis Majano",active=true} );

Refresh the state of an entity or array of entities from the database

Returns

• This function returns back the BaseORMService (this)

Arguments

Examples

var user = storage.getVar("UserSession");
ormService.refresh( user );

var users = [user1,user2,user3];
ormService.refresh( users );

Finds and returns the first result for the given query or throws an exception if not found, this method delegates to the findIt() method

Returns

• This function returns any

• This function could throw an EntityNotFound exception

Arguments

Examples

// My First Post
ormService.findOrFail("from Post as p where p.author='Luis Majano'");
// With positional parameters
ormService.findOrFail("from Post as p where p.author=?", ["Luis Majano"]);
// with a named parameter (since 0.5)
ormService.findOrFail("from Post as p where p.author=:author and p.isActive=:active", { author="Luis Majano",active=true} );

Find all/single entities by example

Returns

• This function returns array

Arguments

Examples

Find one entity (or null if not found) according to a criteria structure ex: findWhere(entityName="Category", {category="Training"}), findWhere(entityName="Users",{age=40,retired=false});

Returns

• This function returns any

Arguments

Examples

// Find a category according to the named value pairs I pass into this method
var category = ormService.findWhere(entityName="Category", criteria={isActive=true, label="Training"});
var user = ormService.findWhere(entityName="User", criteria={isActive=true, username=rc.username,password=rc.password});

Find all the entities for the specified query, named or positional arguments or by an example entity

Returns

• This function returns array

Arguments

Examples

// find all blog posts
ormService.findAll("Post");
// with a positional parameters
ormService.findAll("from Post as p where p.author=?",['Luis Majano']);
// 10 posts from Luis Majano staring from 5th post ordered by release date
ormService.findAll("from Post as p where p.author=? order by p.releaseDate",['Luis majano'],offset=5,max=10);

// Using paging params
var query = "from Post as p where p.author='Luis Majano' order by p.releaseDate" 
// first 20 posts 
ormService.findAll(query=query,max=20) 
// 20 posts starting from my 15th entry
ormService.findAll(query=query,max=20,offset=15);

// examples with named parameters
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'})
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'}, max=20, offset=5);

// query by example
user = ormService.new(entityName="User",firstName="Luis");
ormService.findAll( example=user );

Here is a collection of useful getter methods for entities by primary identifiers. Getters mostly deal with retrieving entities by primary keys instead of finders which rely on criteria operations. You can use the get() for a single entity, getOrFail() for throwing exceptions if an entity is not found and getAll() for multiple entities.

Find all entities according to criteria structure. Ex: findAllWhere(entityName="Category", {category="Training"}), findAllWhere(entityName="Users", {age=40,retired=true});

Returns

• This function returns array

Arguments

Examples

posts = ormService.findAllWhere(entityName="Post", criteria={author="Luis Majano"});
users = ormService.findAllWhere(entityName="User", criteria={isActive=true});
artists = ormService.findAllWhere(entityName="Artist", criteria={isActive=true, artist="Monet"});

Get an entity using a primary key, if the id is not found this method returns null. You can also pass an id = 0 and the service will return to you a new entity.

Returns

• This function returns any

Arguments

Examples

var account = ormService.get("Account",1);
var account = ormService.get("Account",4);

var newAccount = ormService.get("Account",0);

Get an entity using a primary key, if the id is not found this method throws an EntityNotFound Exception

Returns

• This function returns any

Arguments

Examples

var account = ormService.getOrFail("Account",1);
var account = ormService.getOrFail("Account",4);

var newAccount = ormService.getOrFail("Account",0);

Clear the session removes all the entities that are loaded or created in the session. This clears the first level cache and removes the objects that are not yet saved to the database.

Returns

• This function returns the base service reference (this)

Arguments

Examples

ormService.clear();

Retrieve all the instances from the passed in entity name using the id argument if specified. The id can be a list of IDs or an array of IDs or none to retrieve all. If the id is not found or returns null the array position will have an empty string in it in the specified order

You can use the readOnly argument to give you the entities as read only entities.

You can use the properties argument so this method can return to you array of structs instead of array of objects. The property list must include the as alias if not you will get positional keys.

Example Positional: properties="catID,category Example Aliases: properties="catID as id, category as category, role as role"

You can use the asStream boolean argument to get either an array of objects or a Java stream via cbStreams.

Returns

• This function returns array of entities found

Arguments

Examples

// Get all user entities
users = ORMService.getAll(entityName="User", sortOrder="email desc");
// Get all the following users by id's
users = ORMService.getAll("User","1,2,3");
// Get all the following users by id's as array
users = ORMService.getAll("User",[1,2,3,4,5]);

Evict entity object(s) from the hibernate session or first-level cache.

• An entity object

• An array of entity objects

Returns

• This function returns void

Arguments

Examples

ormService.evict( thisEntity );

Evict all queries in the default cache or the cache region that is passed in.

Returns

• This function returns void

Arguments

Examples

// evict queries that are in the default hibernate cache
ormService.evictQueries();
// evict queries for this service
ormService.evictQueries( ormService.getQueryCacheRegion() );
// evict queries for my artists
ormService.evictQueries( "MyArtits" );

Evict all the collection or association data for a given entity name and collection name from the secondary cache ONLY, not the hibernate session.

Evict an entity name with or without an ID from the secondary cache ONLY, not the hibernate session

Returns

• This function returns void

Arguments

Examples

These methods are used for doing a-la-carte querying of entities with extra pizzaz!

Information about the first-level (session) cache for the current session

Returns

• This function returns struct

Arguments

Examples

// Let's get the session statistics
stats = ormService.getSessionStatistics;

// Lets output it
<cfoutput>
collection count: #stats.collectionCount# <br/>
collection keys: #stats.collectionKeys# <br/>
entity count: #stats.entityCount# <br/>
entity keys: #stats.entityKeys#
</cfoutput>

Checks if the session contains dirty objects that are awaiting persistence

Returns

• This function returns boolean

Arguments

Examples

// Check if by this point we have a dirty session, then flush it
if( ormService.isSessionDirty() ){
  ORMFlush();
}

Merge an entity or array of entities back into the session

Returns

• Same entity if one passed, array if an array of entities passed.

Arguments

Examples

// merge a single entity back
ormService.merge( userEntity );
// merge an array of entities
collection = [entity1,entity2,entity3];
ormService.merge( collection );

Allows the execution of Custom HQL queries with binding, pagination, and many options. Underlying mechanism is ORMExecuteQuery. The params filtering can be using named or positional.

Returns

This function returns multiple formats:

• array of objects

• array of structs

• query

• cbStream

Arguments

Examples