stack/core/src/main/java/org/apache/usergrid/persistence/EntityManager.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.usergrid.persistence;


import java.nio.ByteBuffer;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

import com.google.common.base.Optional;
import org.apache.usergrid.persistence.Query.Level;
import org.apache.usergrid.persistence.cassandra.CassandraService;
import org.apache.usergrid.persistence.entities.Application;
import org.apache.usergrid.persistence.entities.Role;
import org.apache.usergrid.persistence.index.EntityIndex;
import org.apache.usergrid.persistence.index.query.CounterResolution;
import org.apache.usergrid.persistence.index.query.Identifier;
import org.apache.usergrid.persistence.model.entity.Id;

import me.prettyprint.hector.api.mutation.Mutator;


/**
 * The interface class for the data access object for Applications. Each application contains a set of users as well as
 * a hierarchy of groups. A application also includes a set of message inboxes and a set of assets.
 */
public interface EntityManager {

//    public void setApplicationId( UUID applicationId );

    public EntityRef getApplicationRef();

    public Application getApplication() throws Exception;

    public void updateApplication( Application app ) throws Exception;

    public void updateApplication( Map<String, Object> properties ) throws Exception;

    public RelationManager getRelationManager( EntityRef entityRef );

    /** Get all collections for the application. Includes both user defined collections and schema collections */
    public Set<String> getApplicationCollections() throws Exception;

    public Map<String, Object> getApplicationCollectionMetadata() throws Exception;

    public long getApplicationCollectionSize( String collectionName ) throws Exception;

    /**
     * Creates an entity of the specified type attached to the specified application.
     *
     * @param entityType the type of the entity to create.
     * @param properties property values to create in the new entity or null.
     *
     * @return the newly created entity object.
     */
    public Entity create( String entityType, Map<String, Object> properties ) throws Exception;

    public <A extends Entity> A create( String entityType, Class<A> entityClass, Map<String, Object> properties )
            throws Exception;

    public <A extends TypedEntity> A create( A entity ) throws Exception;

    /**
     * Creates an entity of the specified type attached to the specified application.
     *
     * @param importId the UUID to assign to the imported entity
     * @param entityType the type of the entity to create.
     * @param properties property values to create in the new entity or null.
     *
     * @return the newly created entity object.
     *
     * @throws Exception the exception
     */
    public Entity create( UUID importId, String entityType, Map<String, Object> properties )
            throws Exception;

    /**
     * Creates an entity of the specified type attached to the specified application.
     * @param id
     * @param properties
     * @return
     * @throws Exception
     */
    public Entity create(Id id, Map<String, Object> properties )
        throws Exception;
    public void createApplicationCollection( String entityType ) throws Exception;

    public EntityRef getAlias( String aliasType, String alias ) throws Exception;

    /**
     * Get the entity ref from the value
     *
     * @param ownerRef The owner Id of the collection
     * @param collectionName The name of the collection
     * @param aliasValue The value of the alias
     */
    public EntityRef getAlias( EntityRef ownerRef, String collectionName, String aliasValue )
            throws Exception;

    public Map<String, EntityRef> getAlias( String aliasType, List<String> aliases ) throws Exception;

    /**
     * Get aliases from the index with the given value
     *
     * @param ownerRef The id of the collection owner
     * @param collectionName The name of the collection
     * @param aliases The alias property
     */
    public Map<String, EntityRef> getAlias( EntityRef ownerRef, String collectionName,
            List<String> aliases ) throws Exception;

    /**
     * Validates that the entity exists in the datastore meaning that it exists and the type has
     * been loaded if not already provided.
     *
     * @return an validated EntityRef or null.
     */
    public EntityRef validate( EntityRef entityRef ) throws Exception;

    /**
     * Retrieves the entity for the specified entity reference.
     *
     * @param entityRef an Entity reference
     *
     * @return an Entity object for the specified entity reference.
     */
    public Entity get( EntityRef entityRef ) throws Exception;

    public <A extends Entity> A get( UUID entityId, Class<A> entityClass ) throws Exception;

    /**
     * Retrieves a set of Entitues cast to the specified class type.
     *
     * @return a list of entity objects.
     */
    public Results get( Collection<UUID> entityIds, Class<? extends Entity> entityClass,
            Level resultsLevel ) throws Exception;

    /**
     * Retrieves a set of Entities cast to the specified class type.
     *
     * @return a list of entity objects.
     */
    public Results get( Collection<UUID> entityIds, String entityType,
        Class<? extends Entity> entityClass, Level resultsLevel ) throws Exception;

    public Results getEntities(List<UUID> ids, String type);

    /**
     * Updates the entity with the properties and values in the Entity Object.
     *
     * @param entity an Entity object.
     */
    public void update( Entity entity ) throws Exception;

    /**
     * Gets the value for a named entity property. Entity properties must be defined in the schema
     *
     * @param entityRef an entity reference
     * @param propertyName the property name to retrieve.
     *
     * @return the value of the named property or null.
     *
     * @throws Exception the exception
     */
    public Object getProperty( EntityRef entityRef, String propertyName ) throws Exception;

    /**
     * Do a single load of all entities with the given properties.  Efficient if you have a subset of properties, and
     * know the ids of them.  The entity UUID is in the key, the runtime subtype of Entity is in the value.  Note that
     * if an entity cannot be loaded (id doesn't exist) it is simply ignored
     */
    public List<Entity> getPartialEntities( Collection<UUID> ids, Collection<String> properties ) throws Exception;

    /**
     * Gets the properties for the specified entity property.
     *
     * @param entityRef an entity reference
     *
     * @return the property values.
     *
     * @throws Exception the exception
     */
    public Map<String, Object> getProperties( EntityRef entityRef ) throws Exception;

    /**
     * Sets the value for a named entity property. If the property is being index, the index is updated to remove the
     * old value and add the new value.
     *
     * @param entityRef an entity reference
     * @param propertyName the property to set.
     * @param propertyValue new value for property.
     *
     * @throws Exception the exception
     */
    public void setProperty( EntityRef entityRef, String propertyName, Object propertyValue ) throws Exception;

    /**
     * You should only use this method if you are absolutely sure what you're doing. Use setProperty without the
     * override param in most cases. With great power comes great responsibility....
     *
     * @param override set to true to force this value to persist. This will ignore all mutable attributes as well as
     * validation. Use with care
     */
    void setProperty( EntityRef entityRef, String propertyName, Object propertyValue, boolean override )
            throws Exception;

    /**
     * Updates the properties for the specified entity.
     *
     * @param entityRef an entity reference
     * @param properties the properties
     *
     * @throws Exception the exception
     */
    public void updateProperties( EntityRef entityRef, Map<String, Object> properties )
            throws Exception;

    public void deleteProperty( EntityRef entityRef, String propertyName ) throws Exception;

    /**
     * Gets the values from an entity list property. Lists are a special type of entity property
     * that can contain an unordered set of non-duplicate values.
     *
     * @param entityRef an entity reference
     * @param dictionaryName the property list name to retrieve.
     *
     * @return the value of the named property or null.
     *
     * @throws Exception the exception
     */
    public Set<Object> getDictionaryAsSet( EntityRef entityRef, String dictionaryName )
            throws Exception;



    /**
     * Adds the specified value to the named entity list property. Lists are a special type of
     * entity property that can contain an unordered set of non-duplicate values.
     *
     * @param entityRef an entity reference
     * @param dictionaryName the property to set.
     * @param elementValue new value for property.
     *
     * @throws Exception the exception
     */
    public void addToDictionary( EntityRef entityRef, String dictionaryName, Object elementValue )
            throws Exception;

    public void addToDictionary( EntityRef entityRef, String dictionaryName, Object elementName,
            Object elementValue ) throws Exception;

    public void addSetToDictionary( EntityRef entityRef, String dictionaryName,
            Set<?> elementValues ) throws Exception;

    public void addMapToDictionary( EntityRef entityRef, String dictionaryName,
            Map<?, ?> elementValues ) throws Exception;

    public Map<Object, Object> getDictionaryAsMap( EntityRef entityRef, String dictionaryName )
            throws Exception;

    public Object getDictionaryElementValue( EntityRef entityRef, String dictionaryName,
            String elementName ) throws Exception;

    /**
     * Removes the specified value to the named entity list property. Lists are a special type of
     * entity property that can contain an unordered set of non-duplicate values.
     *
     * @param entityRef an entity reference
     * @param dictionaryName the property to set.
     * @param elementValue new value for property.
     *
     * @throws Exception the exception
     */
    public void removeFromDictionary( EntityRef entityRef, String dictionaryName, Object elementValue )
            throws Exception;

    public Set<String> getDictionaries( EntityRef entity ) throws Exception;

    /**
     * Deletes the specified entity.
     *
     * @param entityRef an entity reference
     *
     * @throws Exception the exception
     */
    public void delete( EntityRef entityRef ) throws Exception;

    /**
     * Gets the entities and collections that the specified entity is a member of.
     *
     * @param entityRef an entity reference
     *
     * @return a map of entity references to set of collection names for the entities and
     * collections that this entity is a member of.
     *
     * @throws Exception the exception
     */
    public Map<String, Map<UUID, Set<String>>> getOwners( EntityRef entityRef ) throws Exception;

    /**
     * Return true if the owner entity ref is an owner of the entity;
     *
     * @param owner The owner of the collection
     * @param collectionName The collection name
     * @param entity The entity in the collection
     */
    public boolean isCollectionMember( EntityRef owner, String collectionName, EntityRef entity )
            throws Exception;

    /**
     * Return true if the owner entity ref is an owner of the entity;
     *
     * @param owner The owner of the collection
     * @param connectionName The collection name
     * @param entity The entity in the collection
     */
    public boolean isConnectionMember( EntityRef owner, String connectionName, EntityRef entity )
            throws Exception;



    /**
     * Gets the collections for the specified entity. Collection for a given type are encoded
     * in the schema, this method loads the entity type and returns the collections from the schema.
     *
     * @param entityRef an entity reference
     *
     * @return the collections for the entity type of the given entity.
     *
     * @throws Exception the exception
     */
    public Set<String> getCollections( EntityRef entityRef ) throws Exception;

    /**
     * Gets a list of entities in the specified collection belonging to the specified entity.
     *
     * @param entityRef an entity reference
     * @param collectionName the collection name.
     * @param startResult the start result
     * @param count the count
     *
     * @return a list of entities in the specified collection.
     *
     * @throws Exception the exception
     */
    public Results getCollection( EntityRef entityRef, String collectionName, UUID startResult, int count,
                                  Level resultsLevel, boolean reversed ) throws Exception;


    public Results getCollection( UUID entityId, String collectionName, Query query, Level resultsLevel )
            throws Exception;

    /**
     * Adds an entity to the specified collection belonging to the specified entity entity.
     *
     * @param entityRef an entity reference
     * @param collectionName the collection name.
     * @param itemRef an entity to be added to the collection.
     *
     * @throws Exception the exception
     */
    public Entity addToCollection( EntityRef entityRef, String collectionName, EntityRef itemRef ) throws Exception;

    public Entity addToCollections( List<EntityRef> ownerEntities, String collectionName, EntityRef itemRef )
            throws Exception;

    /**
     * Create the item in a sub collection
     *
     * @param entityRef The owning entity
     * @param collectionName The name of the collection
     * @param itemType The type of the item
     * @param properties The properties for the item
     */
    public Entity createItemInCollection( EntityRef entityRef, String collectionName, String itemType,
                                          Map<String, Object> properties ) throws Exception;

    /**
     * Deletes an entity from the specified collection.
     *
     * @param entityRef an entity reference
     * @param collectionName the collection name.
     * @param itemRef a entity to be deleted and removed from the collection.
     *
     * @throws Exception the exception
     */
    public void removeFromCollection( EntityRef entityRef, String collectionName, EntityRef itemRef)
            throws Exception;

    /**
     * Removes only the edge from the specified collection, the entity is left in-tact
     *
     * @param entityRef an entity reference
     * @param collectionName the collection name.
     * @param itemRef a entity to be removed from the collection.
     *
     * @throws Exception the exception
     */
    public void removeItemFromCollection( EntityRef entityRef, String collectionName, EntityRef itemRef)
        throws Exception;

    public Results searchCollection( EntityRef entityRef, String collectionName, Query query )
            throws Exception;

    public Results searchCollectionConsistent( EntityRef entityRef, String collectionName, Query query, int expectedHits)
        throws Exception;

    public Set<String> getCollectionIndexes( EntityRef entity, String collectionName )
            throws Exception;

    public void copyRelationships( EntityRef srcEntityRef, String srcRelationName,
            EntityRef dstEntityRef, String dstRelationName ) throws Exception;

    /**
     * Connect the specified entity to another entity with the specified connection type.
     * Connections are directional relationships that can be traversed in either direction.
     *
     * @throws Exception the exception
     */
    public ConnectionRef createConnection( ConnectionRef connection ) throws Exception;

    public ConnectionRef createConnection( EntityRef sourceEntity, String connectionType,
                                           EntityRef targetEntityRef ) throws Exception;

    public ConnectionRef createConnection( EntityRef sourceEntity, String pairedConnectionType,
                                           EntityRef pairedEntity, String connectionType,
                                           EntityRef targetEntityRef ) throws Exception;

    public ConnectionRef createConnection(
            EntityRef sourceEntity, ConnectedEntityRef... connections )
            throws Exception;

    public ConnectionRef connectionRef( EntityRef sourceEntity, String connectionType,
                                        EntityRef targetEntityRef ) throws Exception;

    public ConnectionRef connectionRef( EntityRef sourceEntity, String pairedConnectionType,
            EntityRef pairedEntity, String connectionType, EntityRef targetEntityRef )
            throws Exception;

    public ConnectionRef connectionRef( EntityRef sourceEntity, ConnectedEntityRef... connections );

    /**
     * Disconnects two connected entities with the specified connection type. Connections are
     * directional relationships that can be traversed in either direction.
     *
     * @throws Exception the exception
     */

    public void deleteConnection( ConnectionRef connectionRef ) throws Exception;

    public Set<String> getConnectionTypes( EntityRef ref ) throws Exception;


    /**
     * Gets the entities of the specified type connected to the specified entity, optionally
     * matching the specified connection types and/or entity types. Returns a list of entity ids.
     *
     * @param entityRef an entity reference
     * @param connectionType type of connection or null.
     * @param connectedEntityType type of entity or null.
     *
     * @return a list of connected entity ids.
     *
     * @throws Exception the exception
     */
    public Results getTargetEntities(EntityRef entityRef, String connectionType,
                                     String connectedEntityType, Level resultsLevel) throws Exception;

    /**
     * Gets the entities connecting to this entity, optionally with the specified connection
     * type and/or entity type.
     * <p/>
     * e.g. "get users who have favorited this place"
     *
     * @param entityRef an entity reference
     * @param connectionType type of connection or null.
     * @param connectedEntityType type of entity or null.
     *
     * @return a list of entities connecting to this one.
     *
     * @throws Exception the exception
     */
    public Results getSourceEntities(EntityRef entityRef, String connectionType,
                                     String connectedEntityType, Level resultsLevel) throws Exception;

    public Results getSourceEntities(EntityRef entityRef, String connectionType,
                                     String entityType, Level level, int count) throws Exception;

	public Results searchTargetEntities(EntityRef sourceEntity, Query query) throws Exception;


    // Application roles

    public Set<String> getConnectionIndexes( EntityRef entity, String connectionType ) throws Exception;

    public Map<String, String> getRoles() throws Exception;

    public void resetRoles() throws Exception;

    /**
     * Create the role with the title and inactivity
     *
     * @param roleName The name of the role
     * @param roleTitle The human readable title
     * @param inactivity The amount of inactivity time to have the role expire. 0 is infinity, I.E no expiration
     */
    public Entity createRole( String roleName, String roleTitle, long inactivity ) throws Exception;

    public Map createCollectionSettings( String collectionName, String owner ,Map<String, Object> properties );

    void deleteCollectionSettings( String collectionName );

    Object getCollectionSettings( String collectionName );

    public void grantRolePermission( String roleName, String permission ) throws Exception;

    public void grantRolePermissions( String roleName, Collection<String> permissions ) throws Exception;

    public void revokeRolePermission( String roleName, String permission ) throws Exception;

    public Set<String> getRolePermissions( String roleName ) throws Exception;

    public void deleteRole( String roleName ) throws Exception;

    public void deleteRole( String roleName, final Optional<EntityRef> roleRef ) throws Exception;


    public EntityRef getGroupRoleRef( UUID ownerId, String roleName ) throws Exception;

    // Group roles

    public Map<String, String> getGroupRoles( UUID groupId ) throws Exception;

    /** Create a group role with the group id, roleName, and inactivity */
    public Entity createGroupRole( UUID groupId, String roleName, long inactivity ) throws Exception;

    public void grantGroupRolePermission( UUID groupId, String roleName, String permission ) throws Exception;

    public void revokeGroupRolePermission( UUID groupId, String roleName, String permission ) throws Exception;

    public Set<String> getGroupRolePermissions( UUID groupId, String roleName ) throws Exception;

    public void deleteGroupRole( UUID groupId, String roleName ) throws Exception;

    // User role membership

    public Set<String> getUserRoles( UUID userId ) throws Exception;

    public void addUserToRole( UUID userId, String roleName ) throws Exception;

    public void removeUserFromRole( UUID userId, String roleName ) throws Exception;

    // User permissions

    public Set<String> getUserPermissions( UUID userId ) throws Exception;

    public void grantUserPermission( UUID userId, String permission ) throws Exception;

    public void revokeUserPermission( UUID userId, String permission ) throws Exception;

    // User role membership

    public Map<String, String> getUserGroupRoles( UUID userId, UUID groupId ) throws Exception;

    public void addUserToGroupRole( UUID userId, UUID groupId, String roleName ) throws Exception;

    public void removeUserFromGroupRole( UUID userId, UUID groupId, String roleName ) throws Exception;

    public Results getUsersInGroupRole( UUID groupId, String roleName, Level level ) throws Exception;

    public void incrementAggregateCounters( UUID userId, UUID groupId, String category,
            String counterName, long value );

    public Results getAggregateCounters( UUID userId, UUID groupId, String category,
            String counterName, CounterResolution resolution, long start, long finish, boolean pad );

    public Results getAggregateCounters( UUID userId, UUID groupId, UUID queueId, String category,
            String counterName, CounterResolution resolution, long start, long finish, boolean pad );

    public Results getAggregateCounters( Query query ) throws Exception;

    public EntityRef getUserByIdentifier( Identifier identifier ) throws Exception;

    public EntityRef getGroupByIdentifier( Identifier identifier ) throws Exception;

    public Set<String> getCounterNames() throws Exception;

    public Map<String, Long> getEntityCounters( UUID entityId ) throws Exception;

    public Map<String, Long> getApplicationCounters() throws Exception;

    public void incrementAggregateCounters(
            UUID userId, UUID groupId, String category, Map<String, Long> counters );

    public boolean isPropertyValueUniqueForEntity(
            String entityType, String propertyName, Object propertyValue ) throws Exception;

    @Deprecated
    /**
     * Get an entity by UUID.  This will return null if the entity is not found
     */
    public Entity get( UUID id ) throws Exception;

    public <A extends Entity> A get( EntityRef entityRef, Class<A> entityClass ) throws Exception;

    public Map<String, Role> getRolesWithTitles( Set<String> roleNames ) throws Exception;

    public String getRoleTitle( String roleName ) throws Exception;

    public Map<String, Role> getUserRolesWithTitles( UUID userId ) throws Exception;


    // Group role membership

    public Map<String, Role> getGroupRolesWithTitles( UUID userId ) throws Exception;

    public void addGroupToRole( UUID userId, String roleName ) throws Exception;

    public void removeGroupFromRole( UUID userId, String roleName ) throws Exception;

    // Group permissions

    public Set<String> getGroupPermissions( UUID groupId ) throws Exception;

    public void grantGroupPermission( UUID groupId, String permission ) throws Exception;

    public void revokeGroupPermission( UUID groupId, String permission ) throws Exception;


    <A extends Entity> A batchCreate(String entityType, Class<A> entityClass, Map<String, Object> properties, UUID
        importId) throws Exception;
    /**
     * Batch dictionary property.
     *
     * @param batch The batch to set the property into
     * @param entity The entity that owns the property
     * @param propertyName the property name
     * @param propertyValue the property value
     * @param timestampUuid The update timestamp as a uuid
     *
     * @return batch
     *
     * @throws Exception the exception
     */
    Mutator<ByteBuffer> batchSetProperty(Mutator<ByteBuffer> batch, EntityRef entity,
            String propertyName, Object propertyValue, UUID timestampUuid) throws Exception;

    Mutator<ByteBuffer> batchSetProperty(Mutator<ByteBuffer> batch, EntityRef entity,
            String propertyName, Object propertyValue, boolean force, boolean noRead,
            UUID timestampUuid) throws Exception;

    Mutator<ByteBuffer> batchUpdateDictionary(Mutator<ByteBuffer> batch, EntityRef entity,
            String dictionaryName, Object elementValue, Object elementCoValue,
            boolean removeFromDictionary, UUID timestampUuid) throws Exception;

    /**
     * Batch update set.
     *
     * @param batch the batch
     * @param entity The owning entity
     * @param dictionaryName the dictionary name
     * @param elementValue the dictionary value
     * @param removeFromDictionary True to delete from the dictionary
     * @param timestampUuid the timestamp
     *
     * @return batch
     *
     * @throws Exception the exception
     */
    Mutator<ByteBuffer> batchUpdateDictionary(Mutator<ByteBuffer> batch, EntityRef entity,
            String dictionaryName, Object elementValue,
            boolean removeFromDictionary, UUID timestampUuid) throws Exception;

    /**
     * Batch update properties.
     *
     * @param batch the batch
     * @param entity The owning entity reference
     * @param properties the properties to set
     * @param timestampUuid the timestamp of the update operation as a time uuid
     *
     * @return batch
     *
     * @throws Exception the exception
     */
    Mutator<ByteBuffer> batchUpdateProperties(Mutator<ByteBuffer> batch,
            EntityRef entity, Map<String, Object> properties, UUID timestampUuid) throws Exception;

    Set<String> getDictionaryNames(EntityRef entity) throws Exception;

    void insertEntity( EntityRef ref ) throws Exception;

    /** @return the applicationId */
    UUID getApplicationId();

    /** @return the indexBucketLocator */
    IndexBucketLocator getIndexBucketLocator();

    /** @return the cass */
    CassandraService getCass();

    /** For testing purposes */
    public void flushManagerCaches();


    public Entity getUniqueEntityFromAlias(String aliasType, String aliasValue, boolean uniqueIndexRepair);

    public UUID getUniqueIdFromAlias(String aliasType, String aliasValue, boolean uniqueIndexRepair);


    /**
     * Get the outgoing edge types where the entity ref is the source in the graph
     * @param entityRef
     * @return
     */
    Set<String> getConnectionsAsSource(final EntityRef entityRef);


    /**
     * Get the outgoing edge types where the entity ref is the target node in the graph
     * @param entityRef
     * @return
     */
    Set<String> getConnectionsAsTarget(final EntityRef entityRef);

    /**
     * Add a new index to the application for scale
     * @param newIndexName unique identifier for additional index
     * @param shards number of shards
     * @param replicas number of replicas
     * @param writeConsistency only "one, quorum, or all"
     */
    void addIndex(final String newIndexName,final int shards,final int replicas, final String writeConsistency);

    /**
     * init the index
     */
    void initializeIndex();
    EntityIndex.IndexRefreshCommandInfo refreshIndex();
}