3.4. Working with Entities

So far we have seen how we can access services via the GLOBALS object. In the following we will see how to work with entities. Entities are stored objects such as reports, users or TeamSpaces. You can find entities by searching for classes annotated with @Entity. You can also find a list of all entities in our ReportServer SourceForge project https://sourceforge.net/projects/dw-rs/. Download the latest apidocs file from the src directory for this.

Without directly spelling it out, we have in our above example already worked with user objects as the SearchService returns the actual entity objects. In the following we want to show how to access a particular entity by id. Almost all entities have a unique identifier which is usually called id and which normally can be accessed via the getId() method. Ids are in most cases of type Long. Go to the user manager in the administration module and select an arbitrary user (or use your searchuser script and click on a link). The user's id is displayed in the header line of the form that allows to set the user's properties. Let us assume that id is 4.

Usually, when you work with entities you will work with JPA's EntityManager (see http://docs.oracle.com/javaee/6/api/javax/persistence/EntityManager.html). The GLOBALS object provides access to an EntityManager by either the method getEntityManager() or as a Provider via getEntityManagerProvider(). For quick access to an entity it furthermore provides the methods findEntity() and getEntitiesByType(). In the following we want to create a simple script that displays a list of all user objects. In a first step, we only access the user object with id 4 and display its name. We name our script userlist.groovy.

package myscripts

import net.datenwerke.security.service.usermanager.entities.User

GLOBALS.findEntity(User, 4l)

Note the "l" behind the id. This is necessary to tell Groovy that the id is of type Long and not an integer. If you execute the script via

exec userlist.groovy

the user's name is printed. What the findEntity method returned however, was the user object. Let's have a closer look at that object. For this we can either have a look at the source of User (located in net.datenwerke.security.service.usermanager.entities), the javadoc of the User class or we use the terminal command desc which takes as argument an entity name and outputs a description of the entity class. Run

desc User

on the terminal. You see the various database fields that a User object stores. By convention, each field has a corresponding getter and setter. Thus the "username" property could be accessed via "getUsername()". Let us change our script to output the username.

package myscripts

import net.datenwerke.security.service.usermanager.entities.User

User user = GLOBALS.findEntity(User, 4l)

user.username + ' - ' + user.name

If we want to list the username of all users we can use the following adaption

package myscripts

import net.datenwerke.security.service.usermanager.entities.User;

GLOBALS.getEntitiesByType(User).collect{
	it.username
}.join("\n")
3.4.1. Writing to Entities

Suppose we want to do a bulk update, for example, synchronize our user objects with an external database. As you can imagine this is straightforward using ReportServer scripts. In the following we will add a simple comment to the description field of any group. For this, we can use a simple adaption of the above script

package myscripts

import net.datenwerke.security.service.usermanager.entities.Group

GLOBALS.getEntitiesByType(Group).each{
    it.description = "some description"
	tout.println("changed group: " + it.name)
}

tout.println("done")

We call the file editgroups.groovy. To test our script, first go the the user management module in the admin module and create a few groups, let's say groups A and B. If you execute the script via exec editgroups.groovy you should see the following output:

changed group: A
changed group: B
done

However, if you look at your groups A and B nothing has changed, that is, the description was not added. This is because, by default the database transaction spanning a script execution is rolled backed after the script is finished. In order to commit the transaction you need to supply the flag "-c" to the exec command. Call your script via

exec -c editgroups.groovy

If you now inspect the groups in the user management area you will find that, indeed, the description was added. Instead of inspecting the group in the user manager you can do this directly from the terminal via the desc command. As a third parameter the desc command takes an object which is then displayed. Thus, you could, for example, write

desc Group /usermanager/A

if your group is located directly in the root directory. Alternatively, you can specify the object via an hql (hibernate query language) query. Thus, we could also access the Group with name "A" via

desc Group "hql:from Group where name='A'"

In this way, you can also display multiple objects side by side

desc Group "hql:from Group"

To display the result in a new window, that is, the result is not directly added to the terminal window, add the -w flag to the desc command. To complete the picture you can also specify objects on the terminal via type and id. Thus, if your group has id 6, you could also write

desc Group id:Group:6