View Javadoc

1   /*
2   * E-nspire Gemini.
3   * A Java and AspectJ based framework that enables transparent 
4   * bidirectional relationships between Plain Old Java Objects.
5   * 
6   * Copyright (C) 2005 Dragan Djuric
7   * 
8   * This program is free software; you can redistribute it and/or
9   * modify it under the terms of the GNU General Public License
10  * as published by the Free Software Foundation; either version 2
11  * of the License, or (at your option) any later version.
12  * 
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21  * 
22  * Contact the author at dragand@dev.java.net
23  */
24  package com.enspire.gemini.annotation;
25  
26  import java.lang.annotation.ElementType;
27  import java.lang.annotation.Retention;
28  import java.lang.annotation.RetentionPolicy;
29  import java.lang.annotation.Target;
30  
31  /***
32   * <p><a href="http://www.e-nspire.com">e-nspire site</a></p>
33   * Fields annotated as <code>@BidirectionalMany</code> represent container
34   * bidirectional fields (which together with setters/getters form JavaBean properties). 
35   * Bidirectional properties are JavaBean properties that update
36   * the opposite property of their newly added values.
37   * <p>
38   * Example: Company<-->Employee relationship. 
39   * <pre>
40   * public class Employee {
41   *      </b>@BidirectionalOne(
42   *          oppositeName = "employees",
43   *          oppositeType = BidirectionalMany.class)
44   *      private Company company;
45   *      //Usual JavaBeans setters and getters go here if needed...
46   * }
47   * 
48   * public class Company {
49   *      </b>@BidirectionalMany(
50   *          oppositeName = "company")
51   *      private Collection employees;
52   *      //Usual JavaBeans setters and getters go here if needed...
53   * }
54   * </pre>
55   * 
56   * @author Dragan Djuric <code> dragandj@dev.java.net  </code>
57   * @since 1.0
58   */
59  @Retention(RetentionPolicy.RUNTIME)
60  @Target({ElementType.FIELD})
61  public @interface BidirectionalMany {
62      
63      /***
64       * Denotes whether the property should be initialized with a bidirectional
65       * wraper only at first setting or always.
66       * <p>
67       * The default value is <code>false</code>, and this is the option that most
68       * often does not need to be changed. However, some frameworks (for example,
69       * Hibernate) have their own wrappers for properties that are collections, 
70       * lists etc, that should NOT be changed when once are set. If you have
71       * such a requirement, set this value to <code>true</code> and the 
72       * initialization will be performed only on the first setting
73       * (while property value is still <code>null</code>).
74       * 
75       * @return whether the initialization of bidirectional wrapper
76       * is performed only when the old value of the property was 
77       * <code>null</code>
78       */
79      boolean initOnlyFirstTime() default false;
80      
81      /***
82       * The name of the opposite property.
83       * @return the name of the opposite property
84       */
85      String oppositeName();
86      
87      /***
88       * The type of the opposite property. Default value is
89       * <code>BidirectionalOne.class</code>
90       */
91      Class oppositeType() default BidirectionalOne.class;
92  }