findByPrimaryKey

These methods return the instance of a class specified by an input parameter, whose fields are filled with the columns values of the record of the table mapped with the specified input class, and which key values of the record are specified by input parameters too.

Mandragora has three methods findByPrimaryKey:

• findByPrimaryKey(Class realClass,Object[] pkValues)
• findByPrimaryKey(Class realClass,String[] fieldName, Object[] pkValues)
• findByPrimaryKey(Class realClass, Object pkValue)

If in our example the class BookVO is mapped to a table called book, and the primary keys of book are idBook, idCollection, idPublisher,idGroup, if you put the following code:

bookVO will be an instance of BookVO, and his fields values are the correspondent columns values of the record of the table book which keys values are 22,43,11,8.

The order in which values specified in the array Object[] pkValues are compared with the primary key columns depends on the BD implementation detail. For example if the implentation (as is the case) use a DAO with Ojb, the order is the one specified in the repository.xml

If you want specify directly the order you can use for example:

In this way you are explicitly specifying which fields are primary key, and for each one which is his value.

In the case the value object/column, has just one primary key you can use the third method. Such a case is the AuthorVO which only primary key is idAuthor:

authorVO will contain the data of author number 9

If an element with the introduced keys does not exist in the media store a null will be returned.

findByTemplate

A template is an instance of a value object class with some of his field populated. Methods findByTemplate are used to look for all objects in the media store associated with the class of the template, and with the same value for the populated fields.

So if the media store is a RDBMS, and the class of the template is associated to a table, and fields of class are associated to table's columns, these methods return all records (creating for each one an instance of the class, and filling his fields with the values of the relative columns of the record), return all records that match with the template. We say that a record match with a template, if all not null fields of the template have the same value of the relative columns of the record.

Mandragora has three methods findByTemplate:

• findCollectionByTemplate(Object templateVO)
• findObjectByTemplate(Object templateVO)
• findOrderedCollectionByTemplate(Object templateVO, String orderingField, boolean asc)

The three methods have the same behavior, with the only difference that the first one return a collection, and the second one return just one object. If we use the second one, findObjectByTemplate(Object templateVO), if more than one record match with the template, an exception is thrown.

For example if we have a class CarVO with many fields, two of which are color and engine, if we do :

Will be returned all cars whose color is red an whose engine is mercedes.

The third method is like the first one, but an ordering field can be specified, and a parameter specifying if ordering must be ascendant (true value) or descendant (false value) to. Suppose our CarVO has a field named model. If we want our list be ascendantly ordered by the field model we just have to use the third method in the following way:

If no car exists with the specified conditions an empty collection will be returned.

findCollectionByNullFields

There is now only one method to find collection by null fields:

• findCollectionByNullFields(Class clazz, String[] nullFields)

This method looks for all instances of the class specified by the input parameter, which fields specified by the input parameter are null. The class must be mapped to some table of the underlying media store, and the array of strings must specify fields of the class, and these fields must be mapped to columns of the associated table. The method creates and returns a collection of instances of this class, one instance for each record in the related table which columns mapped with the input fields have null values In the example of author, book an publisher, if we want to look for all publisher which description and name are both null we can do:

Strings could be a path to the fields of other directly or indirectly related classes too. For example if we want to look for all authors that are related with at least one publisher with a null description we can do:

Note that being a an author related to more books, if just one book of the author belong to a collection published by a publisher with a null description, the author will be added to the collection to return. If no instance can be found an empty collection will be returned.

findCollectionByLogicCondition

Before reading have a look to LogicCondition

Methods that find collections by logic conditions are used to look for all records of a table, in the media store associated with the class specified in input, that match with a specified condition.

The methods that use logic conditions are:

• findCollectionByLogicCondition(Class clazz,LogicCondition logicCondition)
• findLimitedOrderedCollectionByLogicCondition(Class clazz,LogicCondition logicCondition,String orderingField, boolean asc,int startAtIndex, int endAtIndex)

The best way to illustrate how it works is to show some example.

Suppose you have a value object class called EmployeeVO, and you want all employees with age<35 and a salary >=40000. You have just to do write the code

The collection employeeVOs will hold all instances of EmployeeVO.class where age <=35 and salary >= 40000

Consider now the class diagram described in the introduction; suppose you want to get all authors who wrote at list one book with the publisher named "Mondatori". The logic condition will be:

Now to get the authors we want just do:

An other example: suppose you want now to get all publisher which have between his authors "Monica Gutierrez Sancho" or "Gabriel Garcia Marquez" you have to do:

If you want to get all publisher of the group "Random House Mondatori" you have to do :

There are many ways to build a logic condition. The one exposed here needs to be specified the following input parameters:

• the field on which the condition has to be applied. The field can be one belonging to the class which the condition will be applied to, or a path leading to a field of an other class through the walk of relationship between classes.
• an operator which specifies the condition. Operator accepted are :isNull, isNotNull, IN, NOT IN, <=, >=, <, >, !=, <>, LEFTLIKE, RIGHTLIKE, LIKE, BOTHLIKE.
• the value to be compared to the field with the operator
• The logic condition; it can be just AND or OR
• The other logic condition in AND/OR

These methods are recursive, so you can make a condition long a complex as you want. For each added condition a parenthesis is opened, so the resulting logic condition will be:

findCollectionByOrValues

• findCollectionByOrValues(Class clazz,String property,Collection values)

This method returns all records of a table, in the media store associated with the class specified in input, where the field specified by the input parameter property, has as value one of the values specified by the collection values.

For example, suppose you want all car which engines are mercedes or ford; you just need to create a collection holding the values "mercedes" and "ford" and just do:

findCollectionByFieldsNotEqualsToValues

The method is :

• findCollectionByFieldsNotEqualsToValues(Class clazz,String[] properties,Object[] values)

This method returns all records of a table, in the media store associated with the class specified by the input parameter clazz which has each field in the array properties not equals to the correspondent value in the array values. In other words must be verified the condition: (properties[i]!=values[i]). If arrays are empty all instances will be returned.

findCollectionByAndFieldsOperatorValues

The method is :

• findCollectionByAndFieldsOperatorValues(Class clazz,String[] properties, String[] operators,Object[] values)

This method returns all records of a table in the media store associated with the class specified by the input parameter clazz, as a collection of instances of the same class clazz, which satisfy the condition :

For example, referring to the example in the introduction, suppose you want all books of the publisher with id 10, but not of the collection with id 5, and with published before of 20/01/2004. You should create three arrays, one for the properties, or fields which has to be applied the condition, one for the operators, and one for values.

Operators accepted are : ==,=,<=,>=,<,>,!=,<>

If arrays are empty all instances are returned.

findCollectionByArrayOfFieldsOperatorsMatrixAndOrValues

The method is :

• findCollectionByArrayOfFieldsOperatorsMatrixAndOrValues(Class clazz,String[] properties, String[] operators,Object[][] values)

This method returns all records of a table in the media store associated with the class specified by the input parameter clazz, as a collection of instances of the same class clazz, which satisfy AND-OR condition. The AND-OR condition is the AND of properties[j] operators[j] values[j][i] for each i, in OR for each j. So if we have an M x N matrix (M row and N column) of values, the arrays properties and operators must have both N elements.

So the condition will be:

As example suppose values is a 2X2 matrix where values[0][0]=0,values[0][1]=1,values[1][0]=10,values[1][1]=11

suppose properties="property0", "property1" and suppose operators="<",">"

the condition will be (property0<0 AND property1 >1) OR (property0<10 AND property1>11)

Here is an other example relative to the diagram in the introduction: suppose you want the list of books that satisfy the condition of being published before the 20/01/2005 by the publisher with id 45 in the collections with id greater than 22, or being published before the 15/02/2003 by the publisher with id 40, in collections with id greater than 18. The condition is :

So in java code it will be:

We can resume telling that the elements of each row are in AND between them, and the all the row are in OR between them. Note the condition expressed by each element of the same column has involved the same element of the array properties and the same element of the array operators (in other word the same property and the same operator). For more complex conditions findByLogicCondition can be used.

This method is very useful to find a list of object, that have composite primary key, of which we have primary keys. For example consider that the key of book is :(idBook, idCollection, idPublisher, idGroup). I we want to get the books that have one of the following primary keys: (2,12,34,45) or (13,56,23,11) or (22,43,12,55), the java code will be:

Note that the collection bookVOs can hold less than 3 elements, as some of the primary keys could no exist

Operators accepted are : ==,=,<=,>=,<,>,!=,<>

Note!! Arrays must be not Null!!

findCollectionByFieldInCollection

The method is :

• findCollectionByFieldInCollection(Class clazz,String property,Collection values)

This method returns all records of a table in the media store associated with the class specified by the input parameter clazz, as a collection of instances of the same class clazz, that have the field specified by the input parameter property, that has his value equal to one of ones in the collection values

For example suppose you want all the books of one of the author Monica Gutierrez Sancho, Gabriel Garcia Marquez, Paul Auster.

The java code will be:

If the collection values is null or empty a null will be returned.

searchValueInFields

The method is :

• searchValueInFields(Class clazz,String[] properties,Object value)

This method returns all records of a table in the media store associated with the class specified by the input parameter clazz, as a collection of instances of the same class clazz, that holds the value specified in input in one of fields in the array properties Matching instances must satisfy:

For example suppose you want all the books which title or synopsis hold the sentence "I will tell you the secret". You should do:

retrieveReference

The method is :

• retrieveReference(Object pInstance, String pAttributeName)

The object pInstance must be of a class that have the value of pAttributeName as name of one of his property; this property must refer to an other object or collection of objects. The referenced object or collection will be loaded from the underlying media store. For example suppose you have an object called bookVO of the class BookVO. One of his field is authorVOs, that is a collection. If you want the authors of the book be loaded from the media store, each one in an instance of AuthorVO, and all the instance put in a the collection, bookVO.authorVOs you must do:

As an other example, if you have an object publisherVO, instance of PublisherVO, and you want populate his field groupVO, representing the group that hold the publisher represented by publisherVO you must do:

This method overwrite the existing value of the referenced object or collection that are being retrieved.

retrieveAllReferences

The method is :

• retrieveAllReferences(Object pInstance)

With this all objects or collections referenced by pInstance will be loaded from the underlying media store. For example you can see in the figure in the introduction that an instance of the class PublisherVO reference the collection collectionVOs and the object groupVO. If you want to retrieve both of them from the underlying media store you have to do:

This method overwrite the existing value of the referenced object or collection that are being retrieved.

retrieveReferenceInCollection

The method is :

• retrieveReferenceInCollection(Collection collection, String pAttributeName)

This method acts as retrieveReference with the difference that the operation is performed on all elements of collection. For example suppose you have a collection of instances of the class BookVO; we call it bookVOs. If you want to retrieve from the database all the authors of each book in the collection bookVOs, and for each bookVO create the collection of his author and load it in the the collection bookVO.authorVOs you have just to do:

As an other example, if you have a collection of instances of the class PublisherVO; we call it publisherVOs. If you want to retrieve from the database the group of each publisher in the collection publisherVOs, and for each one create an instance of GroupVO and load it in publisherVO.groupVO, you have just to do

This method overwrite the existing value of the referenced objects or collections that are being retrieved.

retrieveAllReferencesInCollection

The method is :

• retrieveAllReferencesInCollection(Collection collection)

This method acts as retrieveAllReferences with the difference that the operation is performed on all elements of collection. For example suppose you have a collection of instances of PublisherVO; we call it publisherVOs. As you can see in the figure in the introduction an instance of the class PublisherVO reference the collection collectionVOs and the object groupVO. If you want to retrieve both of them from the underlying media store for each publisher in the collection publisherVOs you have to do:

This method overwrite the existing value of the referenced objects or collections that are being retrieved.

retrieveAllNullReferences

The method is :

• retrieveAllNullReferences(java.lang.Object pInstance)

This method acts as retrieveAllReferences with the difference that retrieves not null references. For example you can see in the figure in the introduction that an instance of the class PublisherVO reference the collection collectionVOs and the object groupVO. If you have the object publisherVO and you apply the code:

'publisherVO.groupVO' will be retrieved from the database just if 'publisherVO.groupVO' is null. Analogously for 'publisherVOs.collectionVOs'.

retrievePathReference

The method is :

• retrievePathReference(Object valueobjectOrCollection, String path)

This method retrieves references in objects or collections found following the path specified in the input starting from valueobjectOrCollection. Suppose you have an author who wrote many books each of which belongs to a collection of a publishing house hold by a group as you can see in the figure of the introduction. Suppose that your author is represented by the object 'authorVO', and you want that 'authorVO.bookVOs' be filled with instances of the class BookVO representing his books, and for each element 'bookVO', 'bookVO.collectionVO' be retrieved too, and so for 'bookVO.collectionVO.publisherVO' and 'bookVO.collectionVO.publisherVO.groupVO'. The java code is:

So all books of the author will be retrieved, and for each book his collection, publisher and group will be retrieved, and all will be organized in the java structure as the figure in the introduction. The input parameter valueobjectOrCollection, as his name says, can be a value object or a collection of value objects. If it is a collection the same rule will be applied to all his elements. For example if we have a collection of author, that we call 'authorVOs', instead of a single author, and and for each author we would all his books, each one with his collection, publisher and group we should do:

This method automatically detects if the first input parameter is a single value object or a collection, and recursively for each attribute retrieved it detects if they are single value object or a collection. To make it work all class involved in the retrieving must extend the Mandragora class 'it.aco.mandragora.vo.ValueObject'

getReportQueryIterator

The method is :

• getReportQueryIterator(Class clazz,LogicCondition logicCondition, String[] attributes, String[] groupBy)

Before reading have a look to LogicCondition

The parameters clazz and attributes, specify which attributes of which classes (so which table as each class must be mapped to a table) must belong to the report. The parameter clazz is the starting class, and each attribute of the array attributes specify the attribute of clazz if it is not a path expression, while if it is, it is an attribute of the class individuated by the path expression starting from the same class clazz. For example, following the diagram in the introduction, if you put as starting class BookVO, and one of the attribute is "collectionVO.publiherVO.name" this attribute will be the field 'name' of the class PubliherVO. If an attribute is just "title" it will be the field 'title' of the same class BookVO. An attribute can be a function to, for example "sum(somefield)" or "count(somefield)" and so on.. In this case can be specified which attributes will belong to the groupBy clause. The parameter logicCondition specify which rows have to be retrieved This method returns an iterator over a collection of Object[n] of the attributes values, where n, of course is the length of the array attributes Let's see an example: Suppose you want all the books one of the authors of which have full name "Gabriel Garcia Marquez", and for each one you want his title, the description of his collection, and the name of the publisher; The java code will be:

insert

The method is :

• insert(Object insertVO)

Inserts the object insertVO in the underlying datastore. The operation is atomic. Connection management and transaction management are fully delegated. User must no care at all!!. This method returns the same inserted object. For example if you want to insert a new book. You have to do:

In this simple example the referenced objects are null. With the same line 'bd.insert(bookVO);' you can insert a structured object just populating the attributes of bookVO related to the referenced objects, in this case the attributes collectionVO and authorVOs. For example suppose that the book you want to insert has just one author, and that it is a new one, so it must be inserted too int the table of authors; suppose too that the collection 46 is already existing; the code should be;

The behavior of the method insert on the tables mapped with related classes AuthorVO and CollectionVO, (through the attributes authorVOs and collectionVO) depends by the mapping configuration. If you are using the defualt DAO based on PersistenceBroker of Ojb, have a look at the mapping configuration of ojb. Depending by this mapping it could be that all elements of the collection authorVOs be inserted, or if some of that yet existing on on the database, be updated on the database. Note that being the relationship between BookVO and AuthorVO M:N, in both cases (an author be inserted or updated) will be inserted a row in the corresponding table holding the M:N relationship. Analogously for the attribute collectionVO, as in other cases the value object collectionVO could be modified between the retrieve and insert. Setting the mapping properly, in our example, with insertVO will be inserted the book, the author, and updated the collection. All of that just doing 'insert(bookVO)', and without worrying about the connection and transaction management. If you are using Ojb, remember, that for 1:1 mapping if the referenced object is leaved null, the column of the foreign key will be nulled, even if the field of the value object mapped to the column is not null. Consider again the value object bookVO and his attribute collectionVO. Let's say that the class BookVO is mapped to the table BOOK, and the class CollectionVO mapped to the table COLLECTION. BOOK has a column named IDCOLLECTION that is foreign key to COLLECTION, and is mapped to the field idCollection. If bookVO.collectionVO is null, when you insert the bookVO, the column IDCOLLECTION will be null independently of the vale of the attribute idCollection.

Let's see an other example. We want to insert a new publisher whose name is Caballo de Troya, with idPublisher 14, and that must be hold by the group Random House Mondatori, that doesn't exist in the database. So the group must be inserted before to insert the publisher. If you create properly the value object publisherVO, doing 'insert(publisherVO)' all is done automatically:

If the mapping configuration is properly set both publisher and group will be inserted in the correct order in an atomic transaction.

If now you want to insert a new publisher, belonging to the same group, and at the same time you want to modify the attribute description of the group.

In the above example, if the configuration mapping is properly set, will be inserted the publisher and updated the group.

Now we want to insert a new group, with his publishers each one with his collections each one with his books each one with his authors. As you can see in the diagram, as each publisher belongs to just one group, and each collection belongs to just on publisher, and each book belongs to just one collection, surly publishers, collections and books we want to insert don't exist in the database. But as the relationship between authors and books is M:N authors we want to insert can exist or not in the database.

As you can see in the above example you can build a very structured object hold by a main object(here groupVO) and then insert it just with a line of code:'bd.insert(groupVO)'. With just this line of code will be inserted all his publisher collection and so on. That's thanks to ojb, the persistence engine used in the implementention of the DAO (Data Access Object). Mandragora just hide the transaction and connection management. Anyway to use a so powerful insert instruction, you have to take care about the mapping configuration, (for Ojb the repository.xml). In this example you have to take care about circular references, that exists in the diagram. Anyway that the reference exists in the class diagram doesn't mean that it exists in the mapping configuration. If you have circular reference for each publisherVO you must set his attribute groupVO with the correspondent instance of GroupVO, for each collectionVO you must set his attribute publisherVO with the correspondent instance of PublisherVO, and so on. If a circular reference you have set the autoupdate in both side you get in a loop (for example you have the mapping configurated so that when you insert or update a publisher it inserts or updates his group too, and so that when you insert or update the group it inserts or updates his publishers). So take care to map properly.

To what may concern authors and books, if the configuration mapping is set so that when you insert a book it automatically insert or update his authors, as we already told some of the authors we want to insert could already exist in the database, as the relationship between author and book is M:N. If an author (his idAuthor) doesn't exist will be inserted, and if it already exists will be updated with the attributes of the value object; in both cases (an author be inserted or updated) will be inserted a row in the corresponding table holding the M:N relationship.

update

The method is : update(Object updateVO)

It updates the object updateVO in the underlying datastore. The operation is atomic. Connection management and transaction management are fully delegated. User must not care at all!!. For example suppose you want to modify the book identified by the primary key (23,21,45,4). You have to find it by his primary key in the datastore, load it in some value object, make the modification you need, and then store it again.

Of course when you apply the findByPrimaryKey method it could be that bookVO's reference attributes (authorVOs and collectionVO) be populated, depending by the configuration mapping (for ojb look at http://db.apache.org/ojb/docu/guides/basic-technique.html) so that bookVO could be the main object of a complex structure. When then you apply the method update to a value object it could have effect not just on the table mapped to BookVO class, but on tables mapped to related classes too depending always by the mapping configuration. Once you have the bookVO, if his reference attributes (authorVOs and collectionVO) are not populated, you can use the retriever methods, or you can use the setter methods. So, as told you can have a complex structure, and you can modify it as you want, and then with just the line 'bd.update(bookVO)' store it in one atomic transaction, with the proper configuration of the mapping.

Let's see some examples: in the above examples we supposed that the key for BookVO was 'idBook,idCollection,idPublisher,idGroup', the key of CollectionVO was 'idCollection,idPublisher,idGroup', and they key of PublisherVO was 'idPublisher,idGroup'. We suppose now that the key of BookVO is just idBook, the key of CollectionVO is just 'idCollection' and the key of PublisherVO is just 'idPublisher'. We want to get from the database the book identified by the primary key (23), with his collection, publisher and group, but the mapping is configured so that they are not retrieved automatically. We know that this book belongs to the collection 21 but we want to modify it so that it belong to the collection 34 and no more to the collection 21. And in the collection 34 we want to change his description. The mapping is configured so that updating the book, will be updated the collection, updating the collection will be updated the publisher, and with it the group.

Suppose now that the same publisher that holds the the book with idBook 23 in the collection 25, decides to create a new collection and hols the book 23 inside it. You could do so:

In the above example, supposing the autoupdate configuration in the chain, 'bookVO.collectionVO.publisherVO.groupVO', with the line 'bd.update(bookVO)' will be updated the field idCollection in the table of the books, will be inserted a new collection in the table of the collection, that will be referenced with the same publisher of the book.

Let's see now how update works when the main object has attributes that are collections of value objects. Suppose now, that the mapping is configured so that updating the group, publishers referenced be update automatically. Suppose we want to modify the description of the group number 30, modify the description of one of his publishers, concretely the number 12, and add one publisher to his ones.

Note in the above example the use of 'Utils.selectWhereFieldEqualsTo', that returns an element of a collection that must be a value object, that has an attribute with the name specified by the second input parameter that assumes the value specified by the third one. See Queries on collections. The line of code 'bd.update(groupVO)' update in the row of the group number 30 his description, in the row of the publisher number 12 his description too, and insert the new publisher number 199.

Note that if in the collection 'groupVO.getPublisherVOs' you remove some elements before the update, it won't be deleted from the database. So if you do :

publishers won't be deleted. They still are in the database. The method update never delete. If you want do something like that you should use updateCollectionReference, updateCollectionReferences, updateCreateTrees

updateCollection

The method is : updateCollection(Collection updateVOs)

This method updates all objects in the collection updateVOs in an atomic transaction, without user have to carry about connection and transaction management. The collection must be of value objects, and for each of them will this method will act as update or insert depending by if the value object already exists or not in the datastore. The value object of the collection must not necessarily be instance of the same class.

updateCollectionReference

The method is : updateCollectionReference(Object storeVO, String pAttributeName)

This method updates the object storeVO in the same way of update, and delete all objects of the collection associated to pAttributeName. pAttributeName has to be the name of a collection properties. In other words it deletes all objects in the datastore not present in the collection specified by pAttributeName. So if the main object storeVO has a reference collection named pAttributeName configured with an autoupdate, with this method you update the same main object, update all value object of the collection storeVO.pAttributeName, insert all element of this collection not existing in the database, and delete referenced rows in the database the are not in the collection. Connection management and transaction management are fully delegated. User must no care at all as always.

Referring to the diagram at the beginning, suppose that the mapping is configured so that updating the group, publishers referenced be update automatically. Suppose we want to modify the description of the group number 30, modify the description of one of his publishers, concretely the number 12, remove an other publisher,concretely the number 15, and add one publisher to his ones.

Note in the above example the use of 'Utils.selectWhereFieldEqualsTo', that returns an element of a collection that must be a value object, that has an attribute with the name specified by the second input parameter that assumes the value specified by the third one. See Queries on collections. The line of code 'bd.updateCollectionReference(groupVO,"publisherVOs")' update in the row of the group number 30 his description, in the row of the publisher number 12 his description too, and insert the new publisher number 199, and delete the the row of the publisher number 15.

updateCollectionReferences

The method is : updateCollectionReferences(Object storeVO)

This method acts as updateCollectionReference with the difference that it acts on all collection references./br Connection management and transaction management are fully delegated. User must no care at all as always.

storePathCascade

Mandragora has one methods storePathsCascade:

• storePathCascade(Object storeVO,String path)

This method has the same behavior of

• storePathsCascade(Object storeVO,Collection paths, Boolean pathsHasToBeSorted, Boolean storeVOHasToBeStored)

where the collection paths has just one element that is the input parameter path, and where pathsHasToBeSorted and storeVOHasToBeStored are both true

storePathsCascade

Mandragora has one methods storePathsCascade:

• storePathsCascade(Object storeVO,Collection paths, Boolean pathsHasToBeSorted, Boolean storeVOHasToBeStored)

This method creates or updates the value objects on a tree performing insert and update operations. The tree is represented by storeVO, that is the value object root, and paths, that is a collection of strings that are the paths of the tree from the root Each element of paths is a dot separated list of attributes; for example it could be:

attribute_1.attribute_2.attribute_3.attribute_4

We will deal with storeVO as attribute_0. The nodes of level i of the tree are all labeled attribute_i. The generic attribute_i can represent a value object or a collection. The attribute_i must be a property of attribute_i-1 if attribute_i-1 is a value object, and must be a property of each element ofattribute_i-1 if attribute_i-1 is a collection. So storeVO must have a property named attribute_1 that can be a value object or a collection; the value object or each element of the collection must have a property named attribute_2 that can be a value object or a collection too. And so on. Nodes of level i in the tree will be value objects that are the property named attribute_i or all elements (that are value objects too) of collections that are the property named attribute_i.

When called this method apply the following algorithm:

Suppose you have a class diagram representing the structure of your value object like the following:

and that you have a value object as represented by the following object diagram:

To store all this structure you have just to do:

Note that existing object are updated, while new ones are inserted, and in both cases, the right relationship are stored as well, even if not specified by the value objects attributes representing such relationships.

The collection of paths must be ordered to make the method work, anyway, of it is not , specifying the input parameter pathsHasToBeSorted true, the method will order it for you.

The parameter storeVOHasToBeUpdated states if, in the case that rootVO already exists in the database, rootVO must be updated in the database or not.

updateCreateTrees

Mandragora has three methods updateCreateTrees:

• updateCreateTrees(Object rootVO,Collection trees)
• updateCreateTrees(Object storeVO, Collection trees, Boolean storeVOHasToBeUpdated)
• updateCreateTrees(Object storeVO,Collection trees, Boolean storeVOHasToBeUpdated, Boolean deleteChangedOneToOne, Boolean applyDeletePathCascade, Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

These methods create or update a collection of trees in the underlying media store, performing delete, insert, and update operations. All trees have a common root that is rootVO, that can be considered the main object. The collection of trees is represented by the input parameter trees that is a collection of String. Each element of the collection trees is a dot separated list of attributes; for example one of the element of the collection could be: "attribute_1.attribute_2.attribute_3.attribute_4" that represent a tree with as root the main object rootVO that we may consider as attribute_0. The nodes of level i of a tree represented by the string "attribute_1.attribute_2. .. .attribute_i. ... .attribute_n" are all labeled attribute_i. The generic attribute_i can represent a value object or a collection, and the attribute_i must be an attribute of attribute_i-1. if attribute_i-1 is a value object, and must be an attribute of each element ofattribute_i-1 if attribute_i-1 is a collection. So rootVO must have an attribute named attribute_1 that can be a value object or a collection; the value object or each element of the collection must have an attribute named attribute_2 that can be a value object or a collection too. And so on. Nodes of level i in the tree will be value objects that are the attribute named attribute_i or all elements (that are value objects too) of collections that are the attribute named attribute_i.

The differences between the signatures are the boolean parameters storeVOHasToBeUpdated, deleteChangedOneToOne, applyDeletePathCascade, ifM2NDeleteOnlyRelationship, deleteOneToOne.

The parameter storeVOHasToBeUpdated states if, in the case that rootVO already exists in the database, rootVO must be updated in the database or not. The default is true, so executing the first of the two signatures is equivalent to execute the second one with parameter storeVOHasToBeUpdated equal to true.

The parameter deleteChangedOneToOne specifies if in 1 to 1 relationships, if the child is changed with respect to the media store relationship, the element in the media store has to be deleted or not. If not specified is assumed to be false.

The parameter applyDeletePathCascade specifies if an object to delete across the codetrees/code have to be deleted with cascade on the remaining codetrees/code, or have to be just a simple delete. If not specified is assumed to be true.

The parameter ifM2NDeleteOnlyRelationship specifies if when an object have to be deleted and has a M2N relationship with its father on the codepath/code, the object have to be deleted or just its relationship with the father. If not specified is assumed to be true.

The parameter deleteOneToOne specifies if applying the delete cascade, when found a 1 to 1 relationship, the cascade must still be applied or not. If not specified is assumed to be false.

An example of tree, referring to the class diagram at the beginning could be the following that have some intance of GroupVO as root

The tree represented could be for example:

In this example attributes are always collections. It is not hard imaging some simple value object inside.

Let's see now how this method works on the depicted structure. When called this method apply the following algorithm:

Suppose that we have an instance groupVO of the class GroupVO, as depicted in the above picture, applying the following code:

the database will reflect exactly the data in the picture. So if in the database existed a publisher number 3, referred to our group, it will be deleted , while if the publisher number 2 didn't exist it will be created, and if it existed will be updated, an following deep in the tree, the same for all levels.

delete

The method is : delete(Object deleteVO)

This methods deletes the object deleteVO from the underlying datastore. The operation is atomic. Connection management and transaction management are fully delegated and user must no care at all!

For example if you want to delete the group number 20 just do:

deleteCollection

The method is : deleteCollection(Collection deleteVOs)

This methods deletes all the objects of the collection deleteVOs from the underlying datastore. The operation is atomic. Connection management and transaction management are fully delegated and user must no care at all!

Suppose you want to delete some users paolo, marco, and aldo from your database in an atomic transaction, you have just to do:

deleteMToNRelationshipCollection

The method is : deleteMToNRelationshipCollection(Object left, String leftFieldName, Collection rightCollection)

This method deletes the M2N relationship between the main object left and all the elements of the collection rightCollection, relationship represented by the attribute leftFieldName of left. This method supposes it exists a M2N relationship in the media store between the objects of the class of left and the objects of the class of the elements of the collection rightCollection. If left or rightCollection are null nothing is done.

Suppose you have a valuobject mainVO of the class MainVO, that is related in the media store through a M2N relationship, to many objects of the class ReferenceVO and we want to delete such relation to two of such objects, that we call aReferenceVO and bReferenceVO. We suppose that the class MainVO has an attribute referenceVOs that is a collcetion of instances of ReferenceVO. We have just to do :

Just the relationship between the involved objects is deleted, while the objects aReferenceVO and bReferenceVO are no touched at all.

deleteItemsNotInCollectionsInPath

Mandragora has three methods deleteItemsNotInCollectionsInPath:

• deleteItemsNotInCollectionsInPath(Object rootVO, String path, Boolean applyDeletePathCascade, Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)
• deleteItemsNotInCollectionsInPath(Object rootVO, String path)
• deleteItemsNotInCollectionsInPath(Object rootVO, String path,Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

These methods delete from the underlying media store the items that are not in the collections in the path represented by the input parameter path, and starting from rootVO, where path is a dot separated list of attributes, each one being a value object or a collection of value objects. Starting from the root, if the first attribute of path is a 1 to 1 relationship, if the value of such attribute is null this method ends, otherwise, it carries on recursively using the value of first attribute as the new rootVO and the remaining path as the new path. If the first attribute of path is a collection of the rootVO and it is a 1 TO N or a M TO N relationship with ifM2NDeleteOnlyRelationship == false, this method deletes all the items in the database linked to the item relative to rootVO and that are not present in the collection of the first attribute value. If ifM2NDeleteOnlyRelationship == true only their relationship will be deleted. Depending on the value of the input parameter applyDeletePathCascade, the items will be deleted applying a delete cascade on all the remaining path, in such case if the input parameter deleteOneToOne is true the cascade delete will be applied to the 1 TO 1 relationship as well, otherwise the cascade delete will stop at the first 1 TO 1 relationship found. Whatever will be the value of the input parameter applyDeletePathCascade, if the input parameter ifM2NDeleteOnlyRelationship is true, when a M2N relationship is found only the relationship of the M2N relationship table will be deleted, and the corresponding object  won't be touched in the database. Note that such condition, in the applyDeletePathCascade case, will cause the delete cascade to stop when a M2N relationship is found. Note that the parameter deleteOneToOne will cause just the deletion of ONE TO ONE related objects only of the children of nodes that have been decided to be deleted because not held by some collection, and such parameter don't  force the deletion of ONE TO ONE related objects in the database that are null or have changed on the path. So the deleteOneToOne parameter have sense just in the applyDeletePathCascade ==true case. Finally this method carries on recursively for each one of the children of rootVO held by the first attribute value treated as new rootVO, and with the remaining path as new path. If rootVO is null or path is null or empty or blank character string, nothing is done.

Suppose to have a value object structure like the following:

and that the following object diagram represents objects stored in the media store

If we load such structure, and then we delete from this structure some objects held by some collection, and we apply one method deleteItemsNotInCollectionsInPath the objects deleted in the structure will be deleted in the media store as well, or, it can be that just the relationship are removed.

For example if we remove rst1Path3VO from the collection of Path3VO held by rstPath2VO, and we remove rst3Path4VO from the collection of Path4VO held by rst2Path3VO, applying the method they will be removed from the media store, and there are other effects, depending on which method is applied, and with with which parameters values. If it is applied:

In the media store will be deleted the objects correspondent to rst1Path3VO, rst1Path4VO,rst2Path4VO , rstPath5VO, and rst3Path4VO. Note that rst1Path4VO,rst2Path4VO , rstPath5VO are removed from the media store as cosequence of applyDeletePathCascade==TRUE, and rstPath5VO as consequence of deleteOneToOne==TRUE

If we put it is applied the following ifM2NDeleteOnlyRelationship==True, applying so

In the M to N relationships the referenced objects are not deleted, but just their relationship with the main object. So rst1Path3VO, rst1Path4VO,rst2Path4VO , rstPath5VO, and rst3Path4VO won't be deleted, but just the relationship entry between rstPath2VO and rst1Path3VO, and the relationship entry between rst2Path3VO and rst3Path4VO. Even if there is applyDeletePathCascade==TRUE no more objects are deleted because rst1Path3VO is not deleted.

In the case of deleteOneToOne==FALSE :

in the media store will be deleted the objects correspondent to rst1Path3VO, rst1Path4VO,rst2Path4VO , and rst3Path4VO but not rstPath5VO.

Using the method

is the same of

and using the method

is the same of

deleteItemsNotInCollectionsInPaths

The method is : deleteItemsNotInCollectionsInPaths(Object rootVO, Collection paths, Boolean applyDeletePathCascade, Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

This method has the same behavior of

deleteItemsNotInCollectionsInPath(Object rootVO, String path, Boolean applyDeletePathCascade, Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

but is applied to all paths that are in the collection paths.

deletePathCascade

The method is : deletePathCascade(Object parentVO,String path,Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

This method deletes the main object parentVO and applies a delete cascade on all the elements related trough the relationship along the path. The delete cascade stops at the end of the path or when it finds a 1 to 1 relationship and deleteOneToOne is false, or when it finds a M2N relationship and ifM2NDeleteOnlyRelationship is true. If parentVO is null nothing is done.

Suppose we still have the object rstPath2VO as the figure, that represents what is stored as well. If we apply the method

all the structure will be deleted in the media store.

If we apply the same method with deleteOneToOne=FALSE

all the structure will be deleted in the media store except rstPath5VO. And if ifM2NDeleteOnlyRelationship=TRUE

only rstPath2VO will be deleted with the M2N relationship between rstPath2VO and rst1Path3VO, and between rstPath2VO and rst2Path3VO, and rst1Path3VO and rst2Path3VO won't be deleted nor the objects down them.

deletePathsCascade

The method is : deletePathsCascade(Object parentVO, Collection paths,Boolean ifM2NDeleteOnlyRelationship, Boolean deleteOneToOne)

This method has the same behavior of deletePathCascade, but it is applied to all paths that are in the collection paths. If parentVO is null nothing is done.

buildMap

Mandragora has three methods buildMap:

• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName, String mapValueClassAttributeToSetName, Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName,Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName,Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName,Boolean isValueObjectKeyAttributeNameToSet)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, String valueObjectValueAttributeName, String mapValueClassAttributeToSetName,Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, String valueObjectValueAttributeName,Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, Class mapValueClass)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName, String valueObjectValueAttributeName)
• Map buildMap(Object pInstance, String pAttributeName, String valueObjectKeyAttributeName)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName, String mapValueClassAttributeToSetName, Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName, Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, Boolean isValueObjectKeyAttributeNameToSet, Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName,Boolean isValueObjectKeyAttributeNameToSet, String valueObjectValueAttributeName)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName,Boolean isValueObjectKeyAttributeNameToSet)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, String valueObjectValueAttributeName, String mapValueClassAttributeToSetName,Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, String valueObjectValueAttributeName,Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, Class mapValueClass)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName, String valueObjectValueAttributeName)
• Map buildMap(Collection valueObjectsCollection, String valueObjectKeyAttributeName)

These methods create a new Map using the values of specific attributes of the elements of a collection of value objects provided by input parameters. Such collection can be specified by the two inputs parameters pInstance and pAttributeName, where pInstance is the bean holding the collection to be used and pAttributeName is the name of the attribute of pInstance that represents the collection. So definitively the collection to be used is pInstance.pAttributeName. The collection can be specified too, by the single parameter valueObjectsCollection.

In the case the collection is specified by pInstance.pAttributeName and it is null, it will be retrieved from the media store (see retrieveReference), and if it is still null an empty map will be returned. In the case the collection is specified by valueObjectsCollection and it is null an empty map will be returned as well.

If the collection is not null, if isValueObjectKeyAttributeNameToSet is not null and true, it will be executed the setter method with no arguments on the attribute whose name is represented by the input string valueObjectKeyAttributeName for each element of the collection. So for example, if valueObjectKeyAttributeName == "name", the method setName() will be executed on each element of the collection. (Of course each of such elements must provide that method). Every value object of the collection must have an attribute named as specified by the input string parameter valueObjectKeyAttributeName, with its setter and getter.

If the collection is not null, for each value object of the collection it will be got the value of the attribute specified by valueObjectKeyAttributeName (ie. getName()), and if this value is not null a new entry for the map will be created and its key will be the gotten value of the attribute valueObjectKeyAttributeName (ie. getName()); so it will be created an entry in the map for each element of the collection for which the attribute specified by the input parameter valueObjectKeyAttributeName has not null value. The entry's key will be the value of the same attribute specified by the input parameter valueObjectKeyAttributeName. The entry's value depends by if the input parameter mapValueClass is null or not null.

If mapValueClass is null the entry's value will be the value of the attribute specified by the input parameter valueObjectValueAttributeName.

For example suppose that valueObjectKeyAttributeName == "name" and valueObjectValueAttributeName == "age", for each element of the collection which has element.getName() != null on the created map that will be returned will be done

• map.put(element.getName(),element.getAge()

If the String valueObjectValueAttributeName is null or empty string or blank characters string it will be forced to assume the value of valueObjectKeyAttributeName,that, can't be null, nor empt nor blanck chacters string to not be thrown a ApplicationException. In other words this method will create a map and will do:

• map.put(element.valueObjectKeyAttributeName,element.valueObjectValueAttributeName);

for each element of the collection for which element.valueObjectKeyAttributeName is not null.

If the input parameter mapValueClass is not null a new instance of mapValueClass will be created, with the no arguments constructor, and it will be used as value of the entry being processed of the map to be returned.

As in the previous case, from the element of the collection of value objects that is being processed, it will be gotten the value of the attribute specified by valueObjectValueAttributeName and if not null, it will used to set in the mapValueClass class the attribute specified by the input parameter mapValueClassAttributeToSetName.

For example suppose that mapValueClass==Age.class, and mapValueClassAttributeToSetName == "yearsOld", the entry value relative to the value object that is being processed will be new Age(), and if element.getAge() is not null, on the Age instance will be applied setYearsOld(element.getAge())

Of course the mapValueClass must have available the no arguments constructor; the attribute specified by valueObjectValueAttributeName must exist in the elements of the collection, and the attribute specified by mapValueClassAttributeToSetName must exist in the mapValueClass class. If the input string parameter mapValueClassAttributeToSetName is null, or empty string, or blank character string, it will be forced to assume the value of valueObjectValueAttributeName, that in turn, in the same condition is forced to assume the value of valueObjectKeyAttributeName.

Finally the newly created instance of mapValueClass will be used as entry's value of the map, doing:

• map.put(element.valueObjectKeyAttributeName, new instance of mapValueClass);

  ---