Model API

List all members

A List of all collection Member instances can be retrieved from the database with the list() method:

List<Member> everybody = persons.list()
everybody.each { person ->
    println person.firstname
}

List a subset of members

A List of the subset of Member objects can be retrieved by passing a filtering condition to the list method as an argument (see Filter Conditions section below for further details):

List<Member> somePersons = persons.list(firstname__startswith: 'Jo')
somePersons.each { person ->
    println person.birthdate
}

Create a new member

A new Member instance can be created and saved into the backing database with the create(Member) method:

Member member = new Member(firstname:'Joe', birthdate:'1978-01-21', ischild: true)
Member person = persons.create(member)

A shortcut is provided to simply send in a Map:

Member person = persons.create(firstname:'Joe', birthdate:'1978-01-21', ischild: true)

Retrieve a member

An individual collection member can be retrieved from the database with the retrieve(Object) method:

Member person = persons.retrieve(1)

Update a member

A collection member can be updated in the database with the update(Map) method:

Member member = new Member(id: '1', firstname:'Bob', birth_date:'1961-12-05')
Member result = persons.update(member)

Similar to the overloaded create() methods, update() has a convenience method for Maps:

Member result = persons.update(id: '1', firstname:'Bob', birth_date:'1961-12-05')

Delete a member

A collection member can be deleted with the delete(Object) method:

boolean result = persons.delete(1)

The delete() method returns true if the delete operation was successful, otherwise it will return false.

Filtering and excluding members

A filter or exclusion can be applied to a collection to create a new collection that is a subset of the original. Each filtered collection is a distinct collection instance that can be stored, used, and reused independent of its parent. The filter conditions can be passed in dynamically, which eliminates the need for writing a different service for each subset of the data that the client might need. The filters can be chained, therefore each filter creates a new logical subset-collection. However, data is not retrieved from the database until a collection member is actually accessed.

def somePersons = persons.filter(firstname__startswith: 'Jo')
def fewerPersons = somePersons.filter(firstname__endswith: 'e')
....or....
def fewerPersons = persons.filter(firstname__startswith: 'Jo').filter(firstname__endswith: 'e')

def birthdate_not_christmas = persons.exclude(birthdate__month: 12, birthdate__day: 25)

def filtered_and_excluded = persons.filter(ischild: true).exclude(firstname__in: ['Phil', 'Brian'])

Filter conditions

The filter conditions are specified using the following convention: [field name][delimiter][operator]. This convention makes the Model API and HTTP API symmetric (this convention makes it easy to pass filters as URI parameters). The supported filters are:

More than one filter condition can be combined with logical AND using a comma as a separator between the filters:

def somePersons = persons.filter(firstname__startswith: 'Jo', birthdate__before: '1990-12-12')

Paging collections

Often it is impractical and inefficient to return the full results of a collection, the Model API supports a paging scheme you can use to indicate what slice of data a list() or filter() call should return.

def paged_people = collection[10..19].list()

def filtered_paged = collection.filter(firstname__endswith: 'ph')[200..299].list()

def filtered_paged = collection.filter(firstname__endswith: 'ph').limit(201,100).list()

in()

The in() method takes a list of identifiers and returns a map where the key is the id of the Member and the value is the Member itself. This is useful when you have a small set of Members to operate on:

def subset = collection.in([30, 10, 32021])
def member30 = subset[30]
def member32021 = subset[32021]

orderBy()

The orderBy() method returns a new Collection instance with the orderBy attribute of the new Collection set to the parameter of the method. The method takes a list of strings and is provided to be used in the method chaining abilities of filter() and exclude(), and paging:

// SELECT * FROM persons ORDER BY birthdate DESC
def youngest_to_oldest = collection.orderBy(['-birthdate']).list()
// SELECT * FROM persons WHERE firstname LIKE '%don' ORDER BY updated
def filtered = collection.exclude(firstname__endswith: 'don').orderBy(['updated']).list()

latest()

The latest() method returns the most recently updated Member of the Collection instance. This method can be used with filter() and exclude() methods in order to refine the Collection first:

def latest = collection.latest()
def filtered_latest = collection.filter(birthdate__year: '1978').latest()

The latest() method is simply a shortcut for setting the orderBy attribute of the Collection instance, limiting the fetched size to 1 and returning the first result.

iterator()

Collection implements Java's Iterable interface and returns an Iterator of its Members:

def persons = TypeCollection.retrieve('persons')
persons.each { member ->
   println member.firstname
}

size()

The size() method will return the total matched size. If the Collection is unfiltered, the size is the total number of Members in the Collection. Calling this method has the side affect of evaluating the Collection if it has not yet been. The size is cached so subsequent calls to this method do not require accessing the database again:

def persons = TypeCollection.retrieve('persons')
def numberOfPeople = persons.size()

def numberOfSomePeople = persons.filter([first_name__startswith: 'B']).size()

Remember, size() is a method on Collection and can be chained with any method that returns a Collection as shown above with filter().

Named collections

Filters can be specified in the model declaration by defining a named collection:

{
    "fields" : { . . . },

    "collections" : {
        "children": {"memberFilters": {"ischild": true}}
    }
}

In Groovy, a named collection is accessed in the following way:

def persons = TypeCollection.retrieve('persons')
def children = persons.children.list()
def childrenNamedBob = persons.children.[0..4].list(firstname: 'Bob')

Overriding ZRM.delegate()

It is possible to delegate into the ZRM HTTP default implementation while also providing functionality. In order to do this, first create your own Resource Event Handler as shown in the previous example. Instead of completely overriding all behavior, simply call ZRM.delegate() in each method. You can provide your own custom logic before and after the ZRM.delegate() method call.

Further, you can obtain a reference to relevant objects after making the call into the ZRM black box implementation. Collection and Member objects are made available in the /event/resource zone upon completion of the ZRM.delegate() call. Consider the following example:

import zero.resource.TypeCollection

def onList() {
    ZRM.delegate()
    def collection = event.resource.collection[]
}

def onCreate() {
    ZRM.delegate()
    def collection = event.resource.collection[]
    def createdMember = event.resource.member[]
}

def onRetrieve() {
    ZRM.delegate()
    def collection = event.resource.collection[]
    def retrievedMember = event.resource.member[]
}

def onUpdate() {
    ZRM.delegate()
    def collection = event.resource.collection[]
    def updatedMember = event.resource.member[]
 }

def onDelete() {
    ZRM.delegate()
    def collection = event.resource.collection[]
 }

It is important to note that once the ZRM.delegate() method is called, all HTTP response processing has been completed. Thus, the HTTP method has been set and any response body content has been set. Logic done before the ZRM.delegate() call can affect the response, however.

Using the JSON Renderer

The example in the previous section illustrates how to use the TypeCollection, Type, Collection, and Member classes in your own resource event handler. Collection, Type, and Member classes can be assigned as JSON output and handled by custom converters provided by the zero.resource component. In fact, the black box HTTP API leverages the JSON rendering framework as well.