org.deephacks.tools4j.config.spi.BeanManager Maven / Gradle / Ivy
/**
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.deephacks.tools4j.config.spi;
import com.google.common.base.Optional;
import org.deephacks.tools4j.config.admin.query.BeanQuery;
import org.deephacks.tools4j.config.admin.query.BeanQueryBuilder;
import org.deephacks.tools4j.config.model.AbortRuntimeException;
import org.deephacks.tools4j.config.model.Bean;
import org.deephacks.tools4j.config.model.Bean.BeanId;
import org.deephacks.tools4j.config.model.Schema;
import java.io.Serializable;
import java.util.Collection;
import java.util.HashMap;
import java.util.Map;
/**
*
* Bean Manager is used to create and remove bean instances, to find
* beans by their name, and to query over beans.
*
*
* How, when and with what gurantees data are stored (consistency, reliability etc)
* in the underlying storage and published to applications are coordinated by this
* manager.
*
*
* Bean Manager is also responsible for enforcing referential integrity between
* beans and making sure that links arent brooken. This is the only type of
* constraint that is checked, a bean manager is not concerned with schema
* or application validation of any kind.
*
*
* A bean manager should assume that its users already are authorized users,
* maybe authorized through an external security mechanism.
*
*
* Bean managers are free (and encouraged, but not forced) to implement support
* for participating in JTA transactions.
*
*
* @author Kristoffer Sjogren
*/
public abstract class BeanManager implements Serializable {
public static final String PROPERTY = "config.beanmanager";
private static final long serialVersionUID = -246410305338556633L;
/**
* Creates a new bean.
*
*
* If the bean have references to other beans, the bean manager
* make sure that referential integrity is satisfied (that provided
* references exist).
*
*
* Initialized bean references not will be traversed to be created
* recursively/eagerly.
*
* @param bean to create
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void create(final Bean bean) throws AbortRuntimeException;
/**
* This is the collection variant of {@link BeanManager#create(Bean)}.
*
* @see #create(Bean)
* @param beans create
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void create(final Collection beans) throws AbortRuntimeException;
/**
* Create a singleton instance. This method will return silently if the instance
* already exist.
*
* Bean Manager must guarantee that no other instances of this BeanId are created,
* nor that this singleton is removed.
*
* @param singleton the singleton.
*/
public abstract void createSingleton(final BeanId singleton);
/**
* Replace (set) an existing bean instance with provided data.
*
* Already persisted properties and bean references associated with the instance
* will be removed if they are missing from provided bean instances.
*
* If the bean have references to other beans, the bean manager make sure that
* referential integrity is satisfied (that provided references exist).
*
* Initialized bean references not will be traversed and set recursively/eagerly.
*
*
* @param bean to set
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void set(final Bean bean);
/**
* This is the collection variant of {@link BeanManager#set(Bean)}.
*
* @see #set(Bean)
* @param bean to set
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void set(final Collection bean) throws AbortRuntimeException;
/**
* Merges the provided properties with an already existing
* instance.
*
* Already persisted properties and bean references associated with the
* instance will be overwritten if they also exist on the provided bean.
* This is true for collection properties aswell.
*
*
* Values not provided will remain untouched in storage, hence this method
* can be used to set or delete a single property.
*
*
* Initialized bean references not will be traversed and merged
* recursively/eagerly.
*
*
* @param bean The Bean does not have to have its Bean Info
* provided with it.
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void merge(final Bean bean) throws AbortRuntimeException;
/**
* This is the collection variant of {@link BeanManager#merge(Bean)}.
*
* @see #merge(Bean)
* @param bean to merge
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void merge(final Collection bean) throws AbortRuntimeException;
/**
*
* Get a specific instance of a particular schema type.
*
*
*
* Beans will have their basic properties initialized and all
* references traversed and fetched eagerly.
*
*
* @param id to get
* @return A set of beans
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract Optional getEager(final BeanId id) throws AbortRuntimeException;
/**
*
* Get a specific instance of a particular schema type.
*
*
* Beans will have their basic properties and all
* references initialized, but not traversed and fetched eagerly.
*
* @param id to get
* @return Bean
* @throws AbortRuntimeException
*/
public abstract Optional getLazy(final BeanId id) throws AbortRuntimeException;
/**
*
* Bean Manager is responsible for fetching the beans that are to validated when changes
* are made to specific bean instance. The list should contain all the beans that are to
* be validated. The bean manager is free to return all or a subset of beans.
*
*
* This method is optional for bean managers to implement.
*
*
* @param beans targeted bean.
* @return Instances to validate.
* @throws AbortRuntimeException
*/
public Map getBeanToValidate(final Collection beans)
throws AbortRuntimeException {
return new HashMap<>();
}
/**
* Get a singleton instance for a particular schema.
*
* @param schemaName The singleton schema.
* @return The singleton bean.
* @throws IllegalArgumentException if the schema name is not a singleton.
*/
public abstract Optional getSingleton(final String schemaName) throws IllegalArgumentException;
/**
*
* List all instances of a specific schema type.
*
*
* Beans will have their basic properties initialized and all references traversed
* and fetched eagerly.
*
*
* @param schemaName the type of beans to match.
* @return A set of beans.
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract Map list(final String schemaName) throws AbortRuntimeException;
/**
*
* List specific instances of a specific schema type.
*
*
* Beans will have their basic properties initialized and all references traversed
* and fetched eagerly.
*
*
* @param schemaName the type of beans to match.
* @param ids ids of the beans.
* @return A set of beans.
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract Map list(final String schemaName, Collection ids)
throws AbortRuntimeException;
/**
* Delete a bean accoring to id.
*
* Delete operations are not cascading, which means that a bean's references
* are not deleted along with the bean itself.
*
*
* A bean may be referenced by other beans and the bean manager
* make sure that referential integrity is not violated when the bean
* is deleted.
*
*
* @param id delete this bean
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void delete(final BeanId id) throws AbortRuntimeException;
/**
* This method deletes multiple instances of the same schema type.
*
* @see #delete(BeanId)
* @param schemaName -
* @param instanceIds -
* @exception AbortRuntimeException is thrown when the system itself cannot
* recover from a certain event and must therefore abort execution, see
* {@link org.deephacks.tools4j.config.model.Events}.
*/
public abstract void delete(final String schemaName, final Collection instanceIds)
throws AbortRuntimeException;
/**
* Create a new query used for retrieving bean instances using flexible composition
* of Criterion objects, used to narrow number of beans in the result set.
*
* A bean query can also be used to paginate through result sets.
*
* Fields do NOT need to be indexed.
*
* @see {@link BeanQueryBuilder}
*
* @param schema schema to query
* @return Used for composing a query in conjuction with {@link BeanQueryBuilder}.
*/
public abstract BeanQuery newQuery(Schema schema);
}