net.java.ao.ManyToMany Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of activeobjects-core Show documentation
This is the core library for Active Objects. It is generic and can be embedded in any environment. As such it is generic and won't contain all connection pooling, etc.
There is a newer version: 6.1.1
Show newest version
/*
 * Copyright 2007 Daniel Spiewak
 * 
 * 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 net.java.ao;

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

/**
 * Marks a method as relevant only to a many-to-many relation.  This
 * informs ActiveObjects that the return value for the method in question
 * should be determined from a many-to-many relation through the
 * specified type onto the type in the return value.  For example:
 *
 * public interface Person {
 *     // ...
 *
 *     @ManyToMany(Authorship.class)
 *     public Book[] getBooks();
 * }
 *
 * Thus the return value of the getBooks() method
 * would be determined by a query something like the following:
 *
 * SELECT bookID FROM authorships WHERE personID = ?
 *
 * If the {@link #where()} clause is specified, it will be used
 * in addition to the base, necessary criterion to determine the
 * returned entities.  Thus, the many-to-many relation could be referenced
 * in the following way:
 *
 * public interface Person {
 *     // ...
 *
 *     @ManyToMany(value=Authorship.class, where="deleted = FALSE")
 *     public Book[] getBooks();
 * }
 *
 * This would lead to a query like the following:
 *
 * SELECT bookID FROM authorships WHERE personID = ? AND (deleted = FALSE)
 *
 * The value() parameter is not optional.
 *
 * @author Daniel Spiewak
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ManyToMany {

    /**
     * The type through which the many-to-many relation is defined.  For
     * example, if a people table has a many-to-many
     * relation on books, it would most likely be through an
     * authorships table.  Thus, the value of this parameter
     * could be Authorship.class
     */
    Class> value();

    /**
     * The name of the getter method in the joining entity that refers to the annotated entity.
     *
     * If this is not specified, a warning will be logged at migration time, and ActiveObjects may behave in
     * unexpected ways. Future versions of ActiveObjects may require that this property be specified.
     *
     * @see AO-325
     */
    String reverse() default "";

    /**
     * The name of the getter method in the joining entity that refers to the entities to be returned by the annotated
     * method.
     *
     * If this is not specified, a warning will be logged at migration time, and ActiveObjects may behave in
     * unexpected ways. Future versions of ActiveObjects may require that this property be specified.
     *
     * @see AO-325
     */
    String through() default "";

    /**
     * A String clause allowing developer-specified additional
     * conditions to be imposed on the relationship.  The String
     * must be a proper SQL WHERE clause:
     *
     * "deleted = FALSE"
     *
     * One must be extremely careful with this sort of thing though
     * because sometimes (as is the case with the above sample), the
     * unparameterized code may not execute as expected against every
     * database (due to differences in typing and value handling).  Thus,
     * in all but non-trivial cases, defined implementations should be used.
     *
     * @see net.java.ao.Implementation
     */
    String where() default "";
}