org.openxava.model
Class MapFacade

java.lang.Object
  org.openxava.model.MapFacade

public class MapFacade
extends java.lang.Object

Allows manage model objects in Map format.

It's used in generic OpenXava action to make CRUD operations, but if it's convenient for you, you can use directly.

A principle a good design is use maps for generic or automatic things, but in all other cases the use of the model objects directly is better, because the compiler do a good work for us, we can use method calls, etc.

We use the EJB exceptions (CreateException, FinderException, RemoveException, etc) with the typical semantic associated to each. Although the implementation does not use EJB.
We use RemoteException to indicate a system error. Although the implementation is local.
Since version 3.0 MapFacade uses runtime exception for system errors, before (in v2.x) it used RemoteException.
The first parameter of each method is modelName, this is a name of a OpenXava component (Customer, Invoice, etc) or a qualified aggregate (Invoice.InvoiceDetail for example).

Transactional behaviour

MapFacade has transactional behaviour inside your action or test (since 2.2.5). That is, you can write the next code inside an action or test:

 public void execute() throws Exception {
                ...
                MapFacade.create("Customer", customerValue);
                MapFacade.create("Invoice", invoiceValue);
                ... 
 }
 

If Invoice creation fails, the Customer will not be saved; moreover if any other exception is thrown by other sentence of the action. Both Customer and Invoice data will not be saved.
The data is flushed in each MapFacade call, but not committed.
This behavior can be modified for your application with the next property in xava.properties file:

 mapFacadeAutoCommit=true
 

If you mapFacadeAutoCommit=true or mapFacadeAsEJB=true and you execute the above code, if the creation of Invoice fails, the Customer is already saved and committed and it will not be removed.

When autocommit is not used (the default) you can do a commit programatically, using the @{link #commit()} method. In this way:

 public void execute() throws Exception {
                ...
                MapFacade.create("Customer", customerValue);
                MapFacade.commit();
                MapFacade.create("Invoice", invoiceValue);
                ... 
 }
 

Author:

Javier Paniza

Constructor Summary

MapFacade()

Method Summary

static void	addCollectionElement(java.lang.String modelName, java.util.Map keyValues, java.lang.String collectionName, java.util.Map collectionElementKeyValues) Add an element to a collection.
static void	commit() Commit in database the changes done using MapFacade.
static java.lang.Object	create(java.lang.String modelName, java.util.Map values) Creates a new entity from a map with its initial values.
static java.lang.Object	createAggregate(java.lang.String modelName, java.util.Map containerKey, int counter, java.util.Map values) Creates a new aggregate from a map with its initial values.
static java.lang.Object	createAggregate(java.lang.String modelName, java.lang.Object container, int counter, java.util.Map values) Creates a new aggregate from a map with its initial values.
static java.util.Map	createAggregateReturningKey(java.lang.String modelName, java.util.Map containerKey, int counter, java.util.Map values) Creates a new aggregate from a map with its initial values and return a map with the key.
static java.util.Map	createReturningKey(java.lang.String modelName, java.util.Map values) Creates a new entity from a map with its initial values and return a map with the key values of the created entity.
static java.util.Map	createReturningValues(java.lang.String modelName, java.util.Map values) Creates a new entity from a map with its initials values and return a map with the values of created entity.
static java.lang.Object	findEntity(java.lang.String modelName, java.util.Map keyValues) Obtain the entity/aggregate from a map with key values.
static java.util.Map	getKeyValues(java.lang.String modelName, java.lang.Object entity) Obtains the values of the key of entity/aggregate.
static java.util.Map	getValues(java.lang.String modelName, java.util.Map keyValues, java.util.Map memberNames) Obtain the specified values from entity/aggregate from a map with primary key values.
static java.util.Map	getValues(java.lang.String modelName, java.lang.Object entity, java.util.Map memberNames) Obtain the values of the entity/aggregate from the own entity.
static java.util.Map	getValuesByAnyProperty(java.lang.String modelName, java.util.Map searchingValues, java.util.Map memberNames) Obtain the specified values from entity/aggregate searching it by any property.
static void	remove(java.lang.String modelName, java.util.Map keyValues) Remove the entity/aggregate from a map with its key.
static void	removeCollectionElement(java.lang.String modelName, java.util.Map keyValues, java.lang.String collectionName, java.util.Map collectionElementKeyValues) Removes an elemente from a collection.
static void	setValues(java.lang.String modelName, java.util.Map keyValues, java.util.Map values) Set new values to a entity/aggregate that is found from its key values.
static java.lang.Object	toPrimaryKey(java.lang.String entityName, java.util.Map keyValues) Convert from a map with primary key values to primary key object.
static Messages	validate(java.lang.String modelName, java.util.Map values) Validates the sent values but does not create or update the object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MapFacade

public MapFacade()

Method Detail

create

public static java.lang.Object create(java.lang.String modelName,
                                      java.util.Map values)
                               throws CreateException,
                                      ValidationException,
                                      XavaException,
                                      SystemException

Creates a new entity from a map with its initial values.

Parameters:

modelName - OpenXava model name. Not null

values - Initial values for create the entity. Not null. By value semantics.

Returns:

Created entity, not a map it's the created object (EntityBean, POJO object o the form used in the underlying model). Not null.

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

commit

public static void commit()
                   throws SystemException

Commit in database the changes done using MapFacade.

It's used rarely because OpenXava module controller commits automatically after each action execution. ModuleTestBase also commits automatically. It's cannot be used if MapFacade auto commit mode is on or it's used as EJB.

Throws:

java.lang.IllegalStateException - If mapFacadeAutoCommit=true or mapFacadeAsEJB=true in xava.properties

SystemException - System problem. Rollback transaction.

createAggregate

public static java.lang.Object createAggregate(java.lang.String modelName,
                                               java.util.Map containerKey,
                                               int counter,
                                               java.util.Map values)
                                        throws CreateException,
                                               ValidationException,
                                               XavaException,
                                               SystemException

Creates a new aggregate from a map with its initial values.

Parameters:

modelName - OpenXava model name. Not null

containerKey - Key of entity or aggregate that contains this aggregate. By value semantics.

counter - Counter used to generate the aggregate key, indicates the order number. The aggregate implementation can ignorate it.

values - Initial values for create the aggregate. Not null. By value semantics.

Returns:

Aggregate created, not a map but the create object (EntityBean, POJO object o the form used in the underlying model). Not null.

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

createAggregate

public static java.lang.Object createAggregate(java.lang.String modelName,
                                               java.lang.Object container,
                                               int counter,
                                               java.util.Map values)
                                        throws CreateException,
                                               ValidationException,
                                               XavaException,
                                               SystemException

Creates a new aggregate from a map with its initial values.

Parameters:

modelName - OpenXava model name. Not null

container - Container object (or container key in object format) that contains the aggregate.

counter - Counter used to generate the aggregate key, indicates the order number. The aggregate implementation can ignorate it.

values - Initial values for create the aggregate. Not null. By value semantics.

Returns:

Aggregate created, not a map but the create object (EntityBean, POJO object o the form used in the underlying model). Not null.

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

createReturningValues

public static java.util.Map createReturningValues(java.lang.String modelName,
                                                  java.util.Map values)
                                           throws CreateException,
                                                  ValidationException,
                                                  XavaException,
                                                  SystemException

Creates a new entity from a map with its initials values and return a map with the values of created entity.

Parameters:

modelName - OpenXava model name. Not null

values - Initial values to create entity. Not null. By value semantics.

Returns:

A map with the created object values. The properties are the sent ones on create.

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

createReturningKey

public static java.util.Map createReturningKey(java.lang.String modelName,
                                               java.util.Map values)
                                        throws CreateException,
                                               ValidationException,
                                               XavaException,
                                               SystemException

Creates a new entity from a map with its initial values and return a map with the key values of the created entity.

Parameters:

modelName - OpenXava model name. Not null

values - Initial values to create the entity. Not null. By value semantics.

Returns:

A map with key value of created object

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

createAggregateReturningKey

public static java.util.Map createAggregateReturningKey(java.lang.String modelName,
                                                        java.util.Map containerKey,
                                                        int counter,
                                                        java.util.Map values)
                                                 throws CreateException,
                                                        ValidationException,
                                                        XavaException,
                                                        SystemException

Creates a new aggregate from a map with its initial values and return a map with the key.

Parameters:

modelName - OpenXava model name. Not null

containerKey - Key of entity or aggregate that contains this aggregate. By value semantics.

counter - Counter used to generate the aggregate key, indicates the order number. The aggregate implementation can ignorate it.

values - Initial values for create the aggregate. Not null. By value semantics.

Returns:

Key values of created aggregate.

Throws:

CreateException - Logic problem on creation.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

getValues

public static java.util.Map getValues(java.lang.String modelName,
                                      java.util.Map keyValues,
                                      java.util.Map memberNames)
                               throws FinderException,
                                      XavaException,
                                      SystemException

Obtain the specified values from entity/aggregate from a map with primary key values.

The memberNames parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references to a Seller, we can send a map with the next values:

 
 { "number", null }
 { "name", null }
 { "seller", { {"number", null}, {"name", null} } }
 

Parameters:

modelName - OpenXava model name. Not null.

keyValues - Key values of object to find. Not null. By value semantics.

memberNames - Member names to obtain its values. Not null. By value semantics.

Returns:

Map with entity values. Not null.

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

getValuesByAnyProperty

public static java.util.Map getValuesByAnyProperty(java.lang.String modelName,
                                                   java.util.Map searchingValues,
                                                   java.util.Map memberNames)
                                            throws FinderException,
                                                   XavaException,
                                                   SystemException

Obtain the specified values from entity/aggregate searching it by any property.

The memberNames parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references to a Seller, we can send a map with the next values:

 
 { "number", null }
 { "name", null }
 { "seller", { {"number", null}, {"name", null} } }
 

The searchingValues parameters are the values used to search. For example, if you can search by name and surname you can send to searchingValues a map with the next values:

 
 { "name", "JUAN" }
 { "surname", "PEREZ" }
 

In this case it returns the map with the value of the first "JUAN PEREZ" of database.

If you use:

 { "name", "J" }
 

Then it returns the values for the first object of which name starts with 'J'.

If you use:

 { "description", "%BIG" }
 

Then it returns the values for the first object of which description contains "BIG".

Parameters:

modelName - OpenXava model name. Not null.

searchingValues - Values used for search the object. Not null. By value semantics.

memberNames - Member names to obtain its values. Not null. By value semantics.

Returns:

Map with entity values. Not null.

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

getValues

public static java.util.Map getValues(java.lang.String modelName,
                                      java.lang.Object entity,
                                      java.util.Map memberNames)
                               throws XavaException,
                                      SystemException

Obtain the values of the entity/aggregate from the own entity.

The memberNames parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references to a Seller, we can send a map with the next values:

 
 { "number", null }
 { "name", null }
 { "seller", { {"number", null}, {"name", null} } }
 

Parameters:

modelName - OpenXava model name. Not null.

entity - Object to obtain values from it. Not null.

memberNames - Member names to obtain its values. Not null. By value semantics.

Returns:

Map with entity values. Not null.

Throws:

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

getKeyValues

public static java.util.Map getKeyValues(java.lang.String modelName,
                                         java.lang.Object entity)
                                  throws XavaException,
                                         SystemException

Obtains the values of the key of entity/aggregate.

Parameters:

modelName - OpenXava model name. Not null.

entity - Object to obtain key values from it. Not null.

Returns:

Map with key values. Not null.

Throws:

XavaException - Any problem related to OpenXava.

SystemException - System problem.

findEntity

public static java.lang.Object findEntity(java.lang.String modelName,
                                          java.util.Map keyValues)
                                   throws ObjectNotFoundException,
                                          FinderException,
                                          SystemException

Obtain the entity/aggregate from a map with key values.

Parameters:

modelName - OpenXava model name. Not null

keyValues - Key values of entity to find. Not null. By value semantics.

Returns:

The entity or aggregate. Not null

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

SystemException - System problem. Rollback transaction.

remove

public static void remove(java.lang.String modelName,
                          java.util.Map keyValues)
                   throws RemoveException,
                          SystemException,
                          XavaException,
                          ValidationException

Remove the entity/aggregate from a map with its key.

Parameters:

modelName - OpenXava model name. No puede ser nulo.

keyValues - Valores con la clave de la entidad a borrar. Nunca nulo. By value semantics.

Throws:

RemoveException - Logic problem on remove.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

setValues

public static void setValues(java.lang.String modelName,
                             java.util.Map keyValues,
                             java.util.Map values)
                      throws ObjectNotFoundException,
                             FinderException,
                             ValidationException,
                             XavaException,
                             SystemException

Set new values to a entity/aggregate that is found from its key values.

Parameters:

modelName - OpenXava model name. Not null.

keyValues - Key values of object. Not null. By value semantics.

values - New values to set. Not null. By value semantics.

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

validate

public static Messages validate(java.lang.String modelName,
                                java.util.Map values)
                         throws XavaException,
                                SystemException

Validates the sent values but does not create or update the object.

Only validates the sent data, it does not certify that exist all needed data to create a new object.

Parameters:

modelName - OpenXava model name, can be an qualified aggregate. Not null.

values - Values to validate. Not null. By value semantics.

Returns:

Message list with validation errors. Not null.

Throws:

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

toPrimaryKey

public static java.lang.Object toPrimaryKey(java.lang.String entityName,
                                            java.util.Map keyValues)
                                     throws XavaException

Convert from a map with primary key values to primary key object.

Throws:

XavaException

removeCollectionElement

public static void removeCollectionElement(java.lang.String modelName,
                                           java.util.Map keyValues,
                                           java.lang.String collectionName,
                                           java.util.Map collectionElementKeyValues)
                                    throws ObjectNotFoundException,
                                           FinderException,
                                           ValidationException,
                                           RemoveException,
                                           XavaException,
                                           SystemException

Removes an elemente from a collection.

If it's a aggregate remove the aggregate, and if it's a entity reference make the left to point to the parent object, hence left the collection.
Does not delete aggregates directly, but with this method, because thus the needed logic for remove a element from a collection is executed.

Parameters:

modelName - OpenXava model name. Not null.

keyValues - Key value of the container of the collection. Not null. By value semantics.

collectionName - Collection name of the container collection of element to remove. Not null.

collectionElementKeyValues - Key value of element to remove. Not null. By value semantics.

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

ValidationException - Data validation problems.

RemoveException - Logic problem on remove.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.

addCollectionElement

public static void addCollectionElement(java.lang.String modelName,
                                        java.util.Map keyValues,
                                        java.lang.String collectionName,
                                        java.util.Map collectionElementKeyValues)
                                 throws ObjectNotFoundException,
                                        FinderException,
                                        ValidationException,
                                        XavaException,
                                        SystemException

Add an element to a collection.

It does not create the element, only adds it to the collection, therefore for aggregate collections it's not useful using this method, it's better to create the aggregate using createAggregate methods.

Parameters:

modelName - OpenXava model name. Not null.

keyValues - Key value of the container of the collection. Not null. By value semantics.

collectionName - Collection name of the container collection of element to add. Not null.

collectionElementKeyValues - Key value of element to add. Not null. By value semantics.

Throws:

ObjectNotFoundException - If object with this key does not exist

FinderException - Logic problem on find.

ValidationException - Data validation problems.

XavaException - Any problem related to OpenXava. Rollback transaction.

SystemException - System problem. Rollback transaction.