Collection.java

/*
 * Copyright 2012 Jakob Külzer
 * 
 * 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.om.core.api.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.Map;

/**
 * Maps a collection of {@link Entity}s to a {@link Collection} or one of its
 * subtypes.
 * 
 * <p>
 * In order to map a collection, you need at least to add the this annotation.
 * Also, you'll need to indicate what the type of the elements in the collection
 * are by setting the {@link #targetType()}, or, if the target type is different
 * than the
 * 
 * Please note that depending on the concrete collection implementation in use,
 * you'll want to make sure that your collection entries implement
 * {@link #hashCode()} and {@link #equals(Object)}.
 * 
 * @author Jakob Külzer
 * 
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Collection {

	public static final String LOCATION_RELATIVE_USING_FIELDNAME = "";

	/**
	 * Describes the location of where to load the collection from. This has
	 * implications as of how the actual backend will load the data.
	 * 
	 * There are two possible ways of specifying a path to a collection. It can
	 * either be an absolute location, starting with a slash, or relative,
	 * without a beginning slash. If the location is relative, it will be
	 * resolved relative to the node of the containing {@link Entity}.
	 * 
	 * The default is to use the field name as a relative path.
	 */
	String location() default LOCATION_RELATIVE_USING_FIELDNAME;

	/**
	 * Declares the type of the collection items. Each item will be represented
	 * by the given type.
	 * <p>
	 * The referenced type must be a valid {@link Entity}.
	 */
	Class<?> targetType();

	/**
	 * Defines from what the collection should be constructed. Collections can
	 * be created from the child nodes of {@link #location()}, from a
	 * multi-value property indicated by {@link #location()} or by taking all
	 * properties from under {@link #location()}.
	 * 
	 * @see CollectionMode for more details.
	 * @return
	 */
	CollectionMode mode() default CollectionMode.Children;

	/**
	 * Defines how to generate the keys if the collection type is {@link Map}.
	 * Per default {@link MapKeyStrategy#Name} is used. Obviously this setting
	 * will only be used if you're using a Map.
	 * 
	 * @return
	 */
	MapKeyStrategy keyStrategy() default MapKeyStrategy.Name;
}