[[Dashboard | << Back to Dashboard ]] {| align="right" | __TOC__ |} = Exploring the BaseORMService Plugin = == Overview == ******************************************************************************* Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.coldbox.org | www.luismajano.com | www.ortussolutions.com ******************************************************************************* Author : Luis Majano Description : This is a helper ORM service that will help you abstract some complexities when dealing with CF's ORM via Hibernate. You can use this service in its concrete form or you can inherit from it and extend it. Events: This service can also be enabled to produce events via ColdBox Interceptors. However, the application must be a Coldbox application if enabled. TODO: - Add dynamic findBy methods - Add dynamic countBy methods - Add dynamic getBy methods - Dynamic entity methods for the following methods: - new{entityName}() - exists{entityName}() - get{entityName}() - getAll{entityName}() - count{entityName}() - Add find methods by criteria with projections -----------------------------------------------------------------------> == SETQUERYCACHEREGION == === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | queryCacheRegion || string || Yes || --- || |} === Examples === == new == Get a new entity object by entity name and you can pass in any named parameter and the method will try to set them for you. You can pass in the properties structre also to bind the entity === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | properties || struct || No || [runtime expression] || |} === Examples === == populateFromJSON == Populate from JSON, for argument definitions look at the populate method === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | target || any || Yes || --- || |- | JSONString || string || Yes || --- || |- | scope || string || No || || Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to |- | trustedSetter || boolean || No || false || Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties |- | include || string || No || || A list of keys to include in the population ONLY |- | exclude || string || No || || A list of keys to exclude from the population |} === Examples === == count == Return the count of records 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 params with this method: Ex: count('User','age > ? AND name = ?',[40,"joe"]) === Returns === * This function returns ''numeric'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | where || string || No || || |- | params || any || No || [runtime expression] || |} === Examples === == findWhere == Find one entity (or null if not found) according to a criteria structure === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | criteria || struct || Yes || --- || |} === Examples === == clear == 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 ''void'' === Examples === == findAll == Find all the entities for the specified query and params or example === Returns === * This function returns ''array'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | query || string || No || --- || |- | params || any || No || [runtime expression] || |- | offset || numeric || No || 0 || |- | max || numeric || No || 0 || |- | example || any || No || --- || |} === Examples === == GETEVENTHANDLING == === Returns === * This function returns ''boolean'' === Examples === == countWhere == 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 === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |} === Examples === == deleteByQuery == Delete by using an HQL query and iterating via the results, it is not performing a delete query but it actually is a select query that should retrieve objects to remove === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | query || string || Yes || --- || |- | params || any || No || --- || |- | max || numeric || No || 0 || |- | offset || numeric || No || 0 || |- | flush || boolean || No || false || |} === Examples === == getKey == 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 === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |} === Examples === == deleteByID == Delete using an entity name and an incoming id, you can also flush the session if needed. The id parameter can be a single id or an array of IDs to delete The method returns the count of deleted entities. === Returns === * This function returns ''numeric'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | id || any || Yes || --- || |- | flush || boolean || No || false || |} === Examples === == getSessionStatistics == Information about the first-level (session) cache for the current session === Returns === * This function returns ''struct'' === Examples === == saveAll == Saves an array of passed entities in specified order and transaction safe === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entities || any || Yes || --- || An array of entities to save |- | forceInsert || any || No || false || |- | flush || any || No || false || |} === Examples === == isSessionDirty == Checks if the session contains dirty objects that are awaiting persistence === Returns === * This function returns ''boolean'' === Examples === == get == Get an entity using a primary key, if the id is not found this method returns null, if the id=0 or blank it returns a new entity. === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | id || any || Yes || --- || |} === Examples === == populateFromQuery == Populate from Query, for argument definitions look at the populate method.
=== Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | target || any || Yes || --- || |- | qry || any || Yes || --- || The query to use for population |- | rowNumber || numeric || No || 1 || |- | scope || string || No || || Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to |- | trustedSetter || boolean || No || false || Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties |- | include || string || No || || A list of keys to include in the population ONLY |- | exclude || string || No || || A list of keys to exclude from the population |} === Examples === == exists == Checks if the given entityName and id exists in the database, this method does not load the entity into session === Returns === * This function returns ''boolean'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || any || Yes || --- || |- | id || any || Yes || --- || |} === Examples === == getPropertyNames == Returns the Property Names of the entity === Returns === * This function returns ''array'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |} === Examples === == evict == Evict an entity from session, the id can be a string or structure for the primary key You can also pass in a collection name to evict from the collection === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | collectionName || string || No || --- || |- | id || any || No || --- || |} === Examples === == refresh == Refresh the state of an entity or array of entities from the database === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entity || any || Yes || --- || |} === Examples === == merge == Merge an entity or array of entities back into the session === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entity || any || Yes || --- || |} === Examples === == convertIDValueToJavaType == Coverts an ID, list of ID's, or array of ID's values to the proper java type The method returns a coverted array of ID's === Returns === * This function returns ''array'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || any || Yes || --- || |- | id || any || Yes || --- || |} === Examples === == findIt == 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 === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | query || string || No || --- || |- | params || any || No || [runtime expression] || |- | example || any || No || --- || |} === Examples === == save == Save an entity using hibernate transactions. You can optionally flush the session also === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entity || any || Yes || --- || |- | forceInsert || boolean || No || false || |- | flush || boolean || No || false || |- | transactional || boolean || No || true || |} === Examples === == delete == Delete an entity using hibernate 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 === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entity || any || Yes || --- || |- | flush || boolean || No || false || |} === Examples === == SETUSEQUERYCACHING == === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | useQueryCaching || boolean || Yes || --- || |} === Examples === == getTableName == Returns the table name of the of the entity === Returns === * This function returns ''string'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |} === Examples === == evictEntity == Evict entity objects from session. === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entities || any || Yes || --- || The argument can be one persistence entity or an array of entities |} === Examples === == list == List all of the instances of the passed in entity class name. You can pass in several optional arguments like a struct of filtering criteria, a sortOrder string, offset, max, ignorecase, and timeout. Caching for the list is based on the useQueryCaching class property and the cachename property is based on the queryCacheRegion class property. === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | criteria || struct || No || [runtime expression] || |- | sortOrder || string || No || || |- | offset || numeric || No || 0 || |- | max || numeric || No || 0 || |- | timeout || numeric || No || 0 || |- | ignoreCase || boolean || No || false || |- | asQuery || boolean || No || true || |} === Examples === == criteriaQuery == Do a hibernate criteria based query with projections. You must pass an array of criterion objects by using the Hibernate Restrictions object === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || any || Yes || --- || |- | criteria || array || No || [runtime expression] || |- | sortOrder || string || No || || |- | offset || numeric || No || 0 || |- | max || numeric || No || 0 || |- | timeout || numeric || No || 0 || |- | ignoreCase || boolean || No || false || |- | asQuery || boolean || No || true || |} === Examples === == findAllWhere == Find all entities according to criteria structure === Returns === * This function returns ''array'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | criteria || struct || Yes || --- || |} === Examples === == criteriaCount == Get the record count using hibernate projections and criterion for specific queries === Returns === * This function returns ''numeric'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || any || Yes || --- || |- | criteria || array || No || [runtime expression] || |} === Examples === == SETEVENTHANDLING == === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | eventHandling || boolean || Yes || --- || |} === Examples === == populateFromXML == Populate from XML, for argument definitions look at the populate method.
=== Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | target || any || Yes || --- || |- | xml || string || Yes || --- || |- | root || string || No || || The XML root element to start from |- | scope || string || No || || Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to |- | trustedSetter || boolean || No || false || Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties |- | include || string || No || || A list of keys to include in the population ONLY |- | exclude || string || No || || A list of keys to exclude from the population |} === Examples === == GETQUERYCACHEREGION == === Returns === * This function returns ''string'' === Examples === == getRestrictions == Get our hibernate org.hibernate.criterion.Restrictions proxy object === Returns === * This function returns ''any'' === Examples === == evictQueries == Evict all queries in the default cache or the cache region passed === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | cacheName || string || No || --- || |} === Examples === == getAll == 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. === Returns === * This function returns ''array'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | id || any || No || --- || |} === Examples === == GETUSEQUERYCACHING == === Returns === * This function returns ''boolean'' === Examples === == executeQuery == Allows the execution of HQL queries using several nice arguments and returns either an array of entities or a query as specified by the asQuery argument. The params filtering can be using named or positional. === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | query || string || Yes || --- || |- | params || any || No || [runtime expression] || |- | offset || numeric || No || 0 || |- | max || numeric || No || 0 || |- | timeout || numeric || No || 0 || |- | asQuery || boolean || No || true || |} === Examples === == deleteAll == Delete all entries for an entity DLM style and transaction safe. It also returns all the count of deletions === Returns === * This function returns ''numeric'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | flush || boolean || No || false || |} === Examples === == sessionContains == Checks if the current session contains the passed in entity === Returns === * This function returns ''boolean'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entity || any || Yes || --- || |} === Examples === == deleteWhere == 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'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |} === Examples === == populate == Simple map to property population for entities === Returns === * This function returns ''void'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | target || any || Yes || --- || |- | memento || struct || Yes || --- || |- | scope || string || No || || Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to |- | trustedSetter || boolean || No || false || Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties |- | include || string || No || || A list of keys to include in the population ONLY |- | exclude || string || No || || A list of keys to exclude from the population |} === Examples === == createService == Create a virtual abstract service for a specfic entity. === Returns === * This function returns ''any'' === Arguments === {| cellpadding="5", class="tablelisting" ! '''Key''' !! '''Type''' !! '''Required''' !! '''Default''' !! '''Description''' |- | entityName || string || Yes || --- || |- | useQueryCaching || boolean || No || [runtime expression] || |- | queryCacheRegion || string || No || [runtime expression] || |- | eventHandling || boolean || No || [runtime expression] || |} === Examples ===