/**
 *
 *  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 com.agfa.hap.sdo;

import java.util.Collection;
import java.util.Iterator;

import commonj.sdo.DataObject;

/**
 * Interface that allows any object to be exposed as {@link DataObject} instances.
 * The implementation is guaranteed to work for DataObject instances as well.
 * @author AMOCZ
 */
public interface DataMapper<T> {

	/**
	 * @return The sdo type that corresponds with this object. It is assumed
	 * that for all properties of this type, appropriate values can be
	 * retrieved from the instance.
	 * @exception throws {@link IllegalArgumentException} in case no
	 * corresponding sdo type can be found.
	 */
	Type getType(T object);

	/**
	 * @return The sdo type that corresponds with this class. It is assumed
	 * that for all properties of this type, appropriate values can be
	 * retrieved from the instance.
	 * @return null if no sdo type can be found
	 * @exception throws {@link IllegalArgumentException} in case no
	 * corresponding sdo type can be found.
	 * TODO 1 mechanism for indication no type was found
	 */
	Type getCorrespondingType(Class clazz);

	/**
	 * @return An iterator over all values of this property of the given
	 * Object. Property should be a many-valued property.
	 */
	Iterator<? extends T> getObjects(T object, Property property);

	/**
	 * @return The value of the property for the given object.
	 */
	Object getProperty(T object, Property property);

	/**
	 * Assigns the given value to the property of the object. If the property
	 * is many-valued, adds the property to the collection of values.
	 */
	void setProperty(T object, Property property, Object value);

	/**
	 * @return if this property is a bulk property for the given implementation clazz. 
	 * Bulk properties
	 * are accessed in bulk (@see {@link #getProperties(Collection, Property, SnapshotDefinition)}
	 * to allow more efficient retrieval.
	 */
	boolean isBulkProperty(Class clazz, Property property);
	
	/**
	 * Return the corresponding values for this bulk property for the given object.
	 * A snapshotdefinition is passed as indication for which child objects are
	 * needed as well.
	 */
	Collection<T> getProperties(Collection<T> object, Property bulkProperty, SnapshotDefinition def);
	
	/**
	 * Marks a property as unavailable ({@see {@link PartialDataObject#isAvailable(Property)}}.
	 */
	void setUnavailable(T object, Property property);

	boolean isProxy(T object);
	
	/**
	 * @return A newly created instance of which the class corresponds to the given type.
	 * @return null if the datamapper is unable to create a class for the given type
	 * @see DataMapper#getCorrespondingType(Class)
	 */
	T create(Type type);

	/**
	 * Create a new proxy. The type is passed as parameter as this accessor might
	 * be usable for multiple types.
	 * @return null if the datamapper is unable to create a proxy for the given type
	 */
	T newProxy(Type type, Object identity);

}