Cayenne Getting Started Guide

In IntelliJ IDEA select File > New > Project.. and then select Maven and click Next. In the dialog shown on the screenshot below, fill the Group Id and Artifact Id fields and click Next.

On next dialog screen you can customize directory for your project and click Finish. Now you should have a new empty project.

Although later in this tutorial we’ll be using Maven to include Cayenne runtime jars in the project, you’ll still need to download Cayenne to get access to the CayenneModeler tool.

Download the latest release. Unpack the distribution somewhere in the file system and start CayenneModeler, following platform-specific instructions. On most platforms it is done simply by doubleclicking the Modeler icon. The welcome screen of the Modeler looks like this:

Click on the New Project button on Welcome screen. A new mapping project will appear that contains a single DataDomain. The meaning of a DataDomain is explained elsewhere in the User Guide. For now it is sufficient to understand that DataDomain is the root of your mapping project.

The next project object you will create is a DataNode. DataNode is a descriptor of a single database your application will connect to. Cayenne mapping project can use more than one database, but for now, we’ll only use one. With "project" selected on the left, click on Create DataNode button on the toolbar (or select Project > Create DataNode from the menu).

A new DataNode is displayed. Now you need to specify JDBC connection parameters. For an in-memory Derby database you can enter the following settings:

Also you will need to change "Schema Update Strategy". Select org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy from the dropdown, so that Cayenne creates a new schema on Derby based on the ORM mapping when the application starts.

Now you will create a DataMap. DataMap is an object that holds all the mapping information. To create it, click on "Create DataMap" button (or select a corresponding menu item). Note that the newly created DataMap is automatically linked to the DataNode that you created in the previous step. If there is more than one DataNode, you may need to link a DataMap to the correct node manually. In other words a DataMap within DataDomain must point to a database described by the map.

You can leave all the DataMap defaults unchanged except for one - "Java Package". Enter org.example.cayenne.persistent. This name will later be used for all persistent classes.

Before you proceed with the actual mapping, let’s save the project. Click on "Save" button in the toolbar and navigate to the tutorial IDEA project folder that was created earlier in this section and its src/main/resources subfolder and save the project there. Now go back to IDEA and you will see two Cayenne XML files.

Note that the location of the XML files is not coincidental. Cayenne runtime looks for cayenne-*.xml file in the application CLASSPATH and src/main/resources folder should already be a "class folder" in IDEA for our project (and is also a standard location that Maven would copy to a jar file, if we were using Maven from command-line).

Lets go back to CayenneModeler where we have the newly created project open and start by adding the ARTIST table. Database tables are called DbEntities in Cayenne mapping (those can be actual tables or database views).

Select "datamap" on the left-hand side project tree and click "Create DbEntity" button (or use "Project > Create DbEntity" menu). A new DbEntity is created. In "DbEntity Name" field enter "ARTIST". Then click on "Create Attribute" button on the entity toolbar. This action changes the view to the "Attribute" tab and adds a new attribute (attribute means a "table column" in this case) called "untitledAttr". Let’s rename it to ID, make it an INTEGER and make it a PK:

Similarly add NAME VARCHAR(200) and DATE_OF_BIRTH DATE attributes. After that repeat this procedure for PAINTING and GALLERY entities to match DB schema shown above.

Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables. Start by creating a one-to-many ARTIST/PAINTING relationship:

Now that the database schema mapping is complete, CayenneModeler can create mappings of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present there is no way to do it for the entire DataMap in one click, so we’ll do it for each table individually.

Now you need to synchronize relationships. Artist and Gallery entities were created when there was no related "Painting" entity, so their relationships were not set.

Unless you want to customize the Java class and property names (which you can do easily) the mapping is complete.

Now go back to IDEA - you should see pairs of classes generated for each mapped entity. You probably also see that there’s a bunch of red squiggles next to the newly generated Java classes in IDEA. This is because our project does not include Cayenne as a Maven dependency yet. Let’s fix it now by adding "cayenne-server" and "cayenne-java8" artifacts in the bottom of the pom.xml file. Also we should tell Maven compile plugin that our project needs Java 8. The resulting POM should look like this:

Your computer must be connected to the internet. Once you edit the pom.xml, IDEA will download the needed Cayenne jar file and add it to the project build path. As a result, all the errors should disappear. In tutorial for console output we use slf4j-simple logger implementation. Due to use SLF4J logger in Apache Cayenne, you can use your custom logger (e.g. log4j or commons-logging) through bridges.

Now let’s check the entity class pairs. Each one is made of a superclass (e.g. _Artist) and a subclass (e.g. Artist). You should not modify the superclasses whose names start with "_" (underscore), as they will be replaced on subsequent generator runs. Instead all custom logic should be placed in the subclasses in org.example.cayenne.persistent package - those will never be overwritten by the class generator.

ObjectContext is an isolated "session" in Cayenne that provides all needed API to work with data. ObjectContext has methods to execute queries and manage persistent objects. We’ll discuss them in the following sections. When the first ObjectContext is created in the application, Cayenne loads XML mapping files and creates a shared access stack that is later reused by other ObjectContexts.

Let’s check what happens when you run the application. But before we do that we need to add another dependency to the pom.xml - Apache Derby, our embedded database engine. The following piece of XML needs to be added to the <dependencies>…​</dependencies> section, where we already have Cayenne jars:

Now we are ready to run. Right click the "Main" class in IDEA and select "Run 'Main.main()'".

In the console you’ll see output similar to this, indicating that Cayenne stack has been started:

Follow the instructions in the logging chapter to tweak verbosity of the logging output.

Persistent classes in Cayenne implement a DataObject interface. If you inspect any of the classes generated earlier in this tutorial (e.g. org.example.cayenne.persistent.Artist), you’ll see that it extends a class with the name that starts with underscore (org.example.cayenne.persistent.auto._Artist), which in turn extends from org.apache.cayenne.CayenneDataObject. Splitting each persistent class into user-customizable subclass (Xyz) and a generated superclass (_Xyz) is a useful technique to avoid overwriting the custom code when refreshing classes from the mapping model.

Let’s for instance add a utility method to the Artist class that sets Artist date of birth, taking a string argument for the date. It will be preserved even if the model changes later:

Now we’ll create a bunch of objects and save them to the database. An object is created and registered with ObjectContext using “newObject” method. Objects must be registered with DataContext to be persisted and to allow setting relationships with other objects. Add this code to the "main" method of the Main class:

Note that at this point "picasso" object is only stored in memory and is not saved in the database. Let’s continue by adding a Metropolitan Museum “Gallery” object and a few Picasso "Paintings":

Now we can link the objects together, establishing relationships. Note that in each case below relationships are automatically established in both directions (e.g. picasso.addToPaintings(girl) has exactly the same effect as girl.setToArtist(picasso)).

Now lets save all five new objects, in a single method call:

Now you can run the application again as described in the previous chapter. The new output will show a few actual DB operations:

So first Cayenne creates the needed tables (remember, we used “CreateIfNoSchemaStrategy”). Then it runs a number of inserts, generating primary keys on the fly. Not bad for just a few lines of code.

It was shown before how to persist new objects. Cayenne queries are used to access already saved objects. The primary query type used for selecting objects is ObjectSelect. It can be mapped in CayenneModeler or created via the API. We’ll use the latter approach in this section. We don’t have too much data in the database yet, but we can still demonstrate the main principles below.

Before we discuss the API for object deletion, lets go back to CayenneModeler and set up some delete rules. Doing this is optional but will simplify correct handling of the objects related to deleted objects. In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for the "paintings" relationship delete rule:

Repeat this step for other relationships:

Now save the mapping.

While deleting objects is possible via SQL, qualifying a delete on one or more IDs, a more common way in Cayenne (or ORM in general) is to get a hold of the object first, and then delete it via the context. Let’s use utility class Cayenne to find an artist:

Now let’s delete the artist:

Since we set up "Cascade" delete rule for the Artist.paintings relationships, Cayenne will automatically delete all paintings of this artist. So when your run the app you’ll see this output:

We need to provide javax servlet-api for our application.

Also to run the web application we’ll use "maven-jetty-plugin". To activate it, let’s add the following piece of code to the pom.xml file, following the "dependencies" section and save the POM:

You are done with the tutorial!