CFMongoDB

cfmongodb.core
Class DBCollection

WEB-INF.cftags.component
        extended by cfmongodb.core.DBCollection

public class DBCollection
extends WEB-INF.cftags.component

Constructor Summary
init([any collectionName], [any mongo])
          Not intended to be invoked directly
 
Method Summary
 any GETMONGOUTIL()
 void SETMONGOUTIL(any mongoUtil)
 any count([struct criteria='[runtime expression]'])
 any distinct([string key], [struct query])
          Runs mongodb's distinct() command
 any drop()
          drops this collection
 array dropIndexes()
          Drops all indexes from the collection
 array ensureGeoIndex([any field], [any min=''], [any max=''])
          Ensures a "2d" index on a single field
 array ensureIndex([array fields], [any unique='false'])
          The array of fields can either be a) an array of field names
 any find([struct criteria='[runtime expression]'], [string keys=''], [numeric skip='0'], [numeric limit='0'], [any sort='[runtime expression]'])
          Find documents matching the given criteria
 any findAndModify([struct query], [struct fields], [struct sort], [boolean remove='false'], [struct update], [boolean returnNew='true'], [boolean upsert='false'])
          findAndModify is critical for queue-like operations
 any findById([any id])
          Returns a single document matching the passed in id (i
 struct findOne([struct criteria='[runtime expression]'])
          Find a single document matching the given criteria
 array getIndexes()
          Returns an array with information about all of the indexes for the collection
private any getMongoDB()
          Get the underlying Java driver's DB object
 any getMongoDBCollection()
          Get the underlying Java driver's DBCollection object for the given collection
 any group([any keys], [any initial], [any reduce], [any query], [any keyf=''], [any finalize=''])
          Executes Mongo's group() command
 any insert([struct doc])
          Inserts a struct into the collection
 any mapReduce([any map], [any reduce], [any outputTarget], [any outputType='REPLACE'], [any query], [any options])
          Executes Mongo's mapReduce command
 any query()
          Build a query object, and then execute that query using find() Query returns a SearchBuilder object, which you'll call functions on
 any remove([any doc])
          Remove one or more documents from the collection
 any removeById([any id])
          Convenience for removing a document from the collection by the String representation of its ObjectId collection
 any save([struct doc])
          Saves a struct into the collection; Returns the newly-saved Document's _id; populates the struct with that _id person = {name="bill", badmofo=true}; collection
 any saveAll([array docs])
          Saves an array of structs into the collection
private any toCF([any dbObject])
private any toMongo([any doc])
private any toMongoOperation([any doc])
 any update([any doc], [any query], [any upsert='false'], [any multi='false'])
          Updates a document in the collection
 
Methods inherited from class WEB-INF.cftags.component
 

Constructor Detail

init

public init([any collectionName], [any mongo])
Not intended to be invoked directly. Always fetch DBCollection objects via mongo.getDBCollection( collectionName )

Parameters:
collectionName
mongo
Method Detail

GETMONGOUTIL

public any GETMONGOUTIL()


SETMONGOUTIL

public void SETMONGOUTIL(any mongoUtil)

Parameters:
mongoUtil

count

public any count([struct criteria='[runtime expression]'])

Parameters:
criteria

distinct

public any distinct([string key], [struct query])
Runs mongodb's distinct() command. Returns an array of distinct values distinctAges = collection.distinct( "KIDS.AGE" ); use query to filter results collection.distinct( "KIDS.AGE", {GENDER="MALE"} )

Parameters:
key
query

drop

public any drop()
drops this collection


dropIndexes

public array dropIndexes()
Drops all indexes from the collection


ensureGeoIndex

public array ensureGeoIndex([any field], [any min=''], [any max=''])
Ensures a "2d" index on a single field. If another 2d index exists on the same collection, this will error

Parameters:
field
min
max

ensureIndex

public array ensureIndex([array fields], [any unique='false'])
The array of fields can either be a) an array of field names. The sort direction will be "1" b) an array of structs in the form of fieldname=direction. Eg: [ {lastname=1}, {dob=-1} ]

Parameters:
fields
unique

find

public any find([struct criteria='[runtime expression]'], [string keys=''], [numeric skip='0'], [numeric limit='0'], [any sort='[runtime expression]'])
Find documents matching the given criteria. Returns a SearchResult object. usage: sort = {"NAME" = -1}; result = collection.find( criteria={"AGE" = {"$gt"=18}}, limit="5", sort=sort ); writeDump( var=result.asArray(), label="For query #result.getQuery().toString()# with sort #result.getSort().toString()#, returning #result.size()# of #result.totalCount()# documents" );

Parameters:
criteria
keys
skip
limit
sort

findAndModify

public any findAndModify([struct query], [struct fields], [struct sort], [boolean remove='false'], [struct update], [boolean returnNew='true'], [boolean upsert='false'])
findAndModify is critical for queue-like operations. Its atomicity removes the traditional need to synchronize higher-level methods to ensure queue elements only get processed once. http://www.mongodb.org/display/DOCS/findandmodify+Command Your "update" doc must apply one of MongoDB's update modifiers (http://www.mongodb.org/display/DOCS/Updating#Updating-update%28%29), otherwise the found document will be overwritten with the "update" argument, and that is probably not what you want.

Parameters:
query
fields
sort
remove
update
returnNew
upsert

findById

public any findById([any id])
Returns a single document matching the passed in id (i.e. the mongo _id) usage: byID = collection.findById( url.personId );

Parameters:
id

findOne

public struct findOne([struct criteria='[runtime expression]'])
Find a single document matching the given criteria. usage: doc = collection.findOne( {"age" = 18} );

Parameters:
criteria

getIndexes

public array getIndexes()
Returns an array with information about all of the indexes for the collection


getMongoDB

private any getMongoDB()
Get the underlying Java driver's DB object


getMongoDBCollection

public any getMongoDBCollection()
Get the underlying Java driver's DBCollection object for the given collection


group

public any group([any keys], [any initial], [any reduce], [any query], [any keyf=''], [any finalize=''])
Executes Mongo's group() command. Returns an array of structs. usage, including optional 'query': result = collection.group( "STATUS,OWNER", {TOTAL=0}, "function(obj,agg){ agg.TOTAL++; }, {SOMENUM = {"$gt" = 5}}" ); See examples/aggregation/group.cfm for detail

Parameters:
keys
initial
reduce
query
keyf
finalize

insert

public any insert([struct doc])
Inserts a struct into the collection

Parameters:
doc

mapReduce

public any mapReduce([any map], [any reduce], [any outputTarget], [any outputType='REPLACE'], [any query], [any options])
Executes Mongo's mapReduce command. Returns a MapReduceResult object basic usage: result = collection.mapReduce( map=map, reduce=reduce, outputTarget="YourResultsCollection" ); See examples/aggregation/mapReduce for detail

Parameters:
map
reduce
outputTarget
outputType
query
options

query

public any query()
Build a query object, and then execute that query using find() Query returns a SearchBuilder object, which you'll call functions on. Finally, you'll use various "execution" functions on the SearchBuilder to get a SearchResult object, which provides useful functions for working with your results. sort = {"NAME" = -1}; kidSearch = collection.query().between("KIDS.AGE", 2, 30).find( keys="", skip=0, limit=0, sort=sort ); writeDump( var=kidSearch.asArray(), label="For query #kidSearch.getQuery().toString()# with sort #kidSearch.getSort().toString()#, returning #kidSearch.size()# of #kidSearch.totalCount()# documents" ); See gettingstarted.cfm for many examples


remove

public any remove([any doc])
Remove one or more documents from the collection. If the document has an "_id", this will remove that single document by its _id. Otherwise, "doc" is treated as a "criteria" object. For example, if doc is {STATUS="complete"}, then all documents matching that criteria would be removed. pass an empty struct to remove everything from the collection: collection.remove( {} );

Parameters:
doc

removeById

public any removeById([any id])
Convenience for removing a document from the collection by the String representation of its ObjectId collection.removeById( url.id );

Parameters:
id

save

public any save([struct doc])
Saves a struct into the collection; Returns the newly-saved Document's _id; populates the struct with that _id person = {name="bill", badmofo=true}; collection.save( person );

Parameters:
doc

saveAll

public any saveAll([array docs])
Saves an array of structs into the collection. Can also save an array of pre-created CFBasicDBObjects people = [{name="bill", badmofo=true}, {name="marc", badmofo=true}]; collection.saveAll( people );

Parameters:
docs

toCF

private any toCF([any dbObject])

Parameters:
dbObject

toMongo

private any toMongo([any doc])

Parameters:
doc

toMongoOperation

private any toMongoOperation([any doc])

Parameters:
doc

update

public any update([any doc], [any query], [any upsert='false'], [any multi='false'])
Updates a document in the collection. NOTE: This function signature *differs* from the mongo shell signature in one important way: mongo shell: update( query, doc, upsert, multi ) cfmongodb: update( doc, query, upsert, multi ) The reason is that this enables more ColdFusion-idiomatic updating, in that we can pass in a single document argument without using named parameters. For example: The "doc" argument will either be an existing Mongo document to be updated based on its _id, or it will be a document that will be "applied" to any documents that match the "query" argument To update a single existing document, simply pass that document and update() will update the document by its _id, overwriting the existing document with the doc argument: person = person.findById(url.id); person.something = "something else"; collection.update( person ); To update a document by a criteria query and have the "doc" argument applied to a single found instance: update = { "set" = {STATUS = "running"} }; query = {STATUS = "pending"}; collection.update( update, query ); To update multiple documents by a criteria query and have the "doc" argument applied to all matching instances, pass multi=true collection.update( update, query, false, false ) Pass upsert=true to create a document if no documents are found that match the query criteria

Parameters:
doc
query
upsert
multi

CFMongoDB