/*
* Copyright (C) 2005-2012 Alfresco Software Limited.
*
* This file is part of Alfresco
*
* Alfresco is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Alfresco is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with Alfresco. If not, see .
*/
package org.alfresco.repo.domain.propval;
import java.io.Serializable;
import java.util.Date;
import java.util.List;
import org.alfresco.repo.domain.CrcHelper;
import org.alfresco.util.Pair;
import org.springframework.dao.DataIntegrityViolationException;
/**
* DAO services for alf_prop_XXX tables.
*
* @author Derek Hulley
* @since 3.2
*/
public interface PropertyValueDAO
{
//================================
// 'alf_prop_class' accessors
//================================
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_class accessor
*
* @param id the ID (may not be null)
*/
Pair> getPropertyClassById(Long id);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_class accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair> getPropertyClass(Class value);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_class accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair> getOrCreatePropertyClass(Class value);
//================================
// 'alf_prop_date_value' accessors
//================================
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_date_value accessor
*
* @param id the ID (may not be null)
*/
Pair getPropertyDateValueById(Long id);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_date_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getPropertyDateValue(Date value);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_date_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getOrCreatePropertyDateValue(Date value);
//================================
// 'alf_prop_string_value' accessors
//================================
/**
* Utility method to get query parameters for case-sensitive string searching
* @see CrcHelper
*/
Pair getPropertyStringCaseSensitiveSearchParameters(String value);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_string_value accessor
*
* @param id the ID (may not be null)
*/
Pair getPropertyStringValueById(Long id);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_string_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getPropertyStringValue(String value);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_string_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getOrCreatePropertyStringValue(String value);
//================================
// 'alf_prop_double_value' accessors
//================================
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_double_value accessor
*
* @param id the ID (may not be null)
*/
Pair getPropertyDoubleValueById(Long id);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_double_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getPropertyDoubleValue(Double value);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_double_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair getOrCreatePropertyDoubleValue(Double value);
//================================
// 'alf_prop_serializable_value' accessors
//================================
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_serializable_value accessor
*
* @param id the ID (may not be null)
*/
Pair getPropertySerializableValueById(Long id);
/**
* FOR INTERNAL USE ONLY: Do not use directly; see interface comments.
*
* alf_prop_serializable_value accessor
*
* @param value the value to find the ID for (may not be null)
*/
Pair createPropertySerializableValue(Serializable value);
//================================
// 'alf_prop_value' accessors
//================================
/**
* Use for accessing unique properties; see interface comments.
*
* alf_prop_value accessor: get a property based on the database ID
*
* @param id the ID (may not be null)
*/
Pair getPropertyValueById(Long id);
/**
* Use for accessing unique properties; see interface comments.
*
* alf_prop_value accessor: find a property based on the value
*
* @param value the value to find the ID for (may be null)
*/
Pair getPropertyValue(Serializable value);
/**
* Use for accessing unique properties; see interface comments.
*
* alf_prop_value accessor: find or create a property based on the value.
* Note: This method will not recurse into maps or collections. Use the
* dedicated methods if you want recursion; otherwise maps and collections will
* be serialized and probably stored as BLOB values.
*
* All collections and maps will be opened up to any depth. To limit this behaviour,
* use {@link #getOrCreatePropertyValue(Serializable, int)}.
*
* @param value the value to find the ID for (may be null)
*/
Pair getOrCreatePropertyValue(Serializable value);
//================================
// 'alf_prop_root' accessors
//================================
/**
* A callback for handling return properties
*/
public interface PropertyFinderCallback
{
public void handleProperty(Long id, Serializable value);
}
/**
* Use for accessing non-unique, exploded properties; see interface comments.
*
* alf_prop_root accessor: get a property based on the database ID
*
* @param id the ID (may not be null)
* @return Returns the value of the property (never null)
* @throws DataIntegrityViolationException if the ID is invalid
*/
Serializable getPropertyById(Long id);
/**
* Use for accessing non-unique, exploded properties; see interface comments.
*
* alf_prop_root accessor: get all properties based on the database IDs
*
* @param ids the IDs (may not be null; may be empty)
* @param callback the callback to handle the results
* @throws DataIntegrityViolationException if any of the the IDs are invalid
*/
void getPropertiesByIds(List ids, PropertyFinderCallback callback);
/**
* Use for accessing non-unique, exploded properties; see interface comments.
*
* alf_prop_root accessor: find or create a property based on the value.
*
* All collections and maps will be opened up to any depth.
*
* @param value the value to create (may be null)
* @return Returns the new property's ID
*/
Long createProperty(Serializable value);
/**
* Use for accessing non-unique, exploded properties; see interface comments.
*
* alf_prop_root accessor: update the property root to contain a new value.
*
* @param id the ID of the root property to change
* @param value the new property value
*/
void updateProperty(Long id, Serializable value);
/**
* Use for accessing non-unique, exploded properties; see interface comments.
*
* alf_prop_root accessor: delete a property root completely
*
* @param id the ID of the root property to delete
*/
void deleteProperty(Long id);
//================================
// 'alf_prop_unique_ctx' accessors
//================================
/**
* alf_prop_unique_ctx accessor: create a unique context with an optional
* associated value.
*
* The DAO ensures that the region-context-value combination will be globally unique.
*
* @param value1 a simple key value (not a collection) (may be null)
* @param value2 a simple key value (not a collection) (may be null)
* @param value3 a simple key value (not a collection) (may be null)
* @param propertyValue1 a value to store against the key (may be null)
* @return Returns the ID-valueId pair of the context
*
* @throws PropertyUniqueConstraintViolation if the combination is not unique
*/
Pair createPropertyUniqueContext(
Serializable value1, Serializable value2, Serializable value3,
Serializable propertyValue1);
/**
* Get the unique context ID and associated shared property ID, or null if no
* such context exists. The associated property may be null even if the unique
* context exists.
*
* @param values a combination of one to three values in order
* @return Returns the ID-valueId pair or null if the context
* doesn't exist.
*
* @see #createPropertyUniqueContext(Serializable, Serializable, Serializable, Serializable)
*/
Pair getPropertyUniqueContext(Serializable value1, Serializable value2, Serializable value3);
/**
* A callback for handling return property unique contexts
*/
public interface PropertyUniqueContextCallback
{
public void handle(Long id, Long propId, Serializable[] keys);
}
/**
* Get unique contexts (unique context ID and associated shared property ID), if any, based on one, two or three context values.
* The associated property may be null even if the unique context exists.
*
* @param values a combination of one to three values in order
*
* @see #createPropertyUniqueContext(Serializable, Serializable, Serializable, Serializable)
*/
void getPropertyUniqueContext(PropertyUniqueContextCallback callback, Serializable ... values);
/**
* Update the unique context, preserving any associated property.
*
* @throws PropertyUniqueConstraintViolation if the combination is not unique
*
* @see #createPropertyUniqueContext(Serializable, Serializable, Serializable, Serializable)
*/
void updatePropertyUniqueContextKeys(
Long id,
Serializable value1, Serializable value2, Serializable value3);
/**
* Update the property associated with a unique context (based on one, two or three context values).
*
* @see #createPropertyUniqueContext(Serializable, Serializable, Serializable, Serializable)
*/
void updatePropertyUniqueContext(Serializable value1, Serializable value2, Serializable value3, Serializable propertyValue);
/**
* @see #createPropertyUniqueContext(Serializable, Serializable, Serializable, Serializable)
*/
void deletePropertyUniqueContext(Long id);
/**
* Delete sets of unique contexts based on one, two or three context values.
*
* @param values a combination of one to three values in order
* @return Returns the number of unique contexts deleted
*/
int deletePropertyUniqueContext(Serializable ... values);
//================================
// Utility methods
//================================
/**
* Utility method to convert property query results into the original value. Note
* that the rows must all share the same root property ID.
*
* If the rows passed in don't constitute a valid, full property - they don't contain all
* the link entities for the property - then the result may be null.
*
* @param rows the search results for a single root property
* @return Returns the root property as originally persisted, or null
* if the rows don't represent a complete property
* @throws IllegalArgumentException if rows don't all share the same root property ID
*/
Serializable convertPropertyIdSearchRows(List rows);
}