Add core interfaces

1 files changed, 120 insertions, 0 deletions

diff --git a/src/main/java/com/amazon/carbonado/Join.java b/src/main/java/com/amazon/carbonado/Join.java
new file mode 100644
index 0000000..eb21e58
--- /dev/null
+++ b/src/main/java/com/amazon/carbonado/Join.java
@@ -0,0 +1,120 @@
+/*

+ * Copyright 2006 Amazon Technologies, Inc. or its affiliates.

+ * Amazon, Amazon.com and Carbonado are trademarks or registered trademarks

+ * of Amazon Technologies, Inc. or its affiliates.  All rights reserved.

+ *

+ * 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 com.amazon.carbonado;

+

+import java.lang.annotation.*;

+

+/**

+ * Identifies a {@link Storable} property as defining a join relationship

+ * with another Storable type. Joins can also refer to their own enclosing

+ * class or interface.

+ * <p>

+ * To complete the join, lists of internal and external properties may be

+ * supplied. If these lists are not supplied, then join is "natural", and the

+ * properties are determined automatically. When the lists are specified, the

+ * join is "explicit". Natural joins are merely a convenience; they can always

+ * be replaced by an explicit join.

+ * <p>

+ * The lists used for explicit joins must have the same length, and each must

+ * have at least one element. Each element in the internal list must refer to

+ * a property defined in this property's class or interface, and each element

+ * in the external list must refer to a matching property defined in the joined

+ * type. The matched up property pairs must not themselves be join properties,

+ * and they must be compatible with each other.

+ * <p>

+ * If the join is made to external properties which do not completely specify a

+ * primary key, then the type of the join property must be a {@link Query} of

+ * the joined type. When the type is a Query, a property mutator method cannot

+ * be defined. The returned query has all of the "with" parameters filled in.

+ * <p>

+ * With a natural join, the internal and external properties are deduced by

+ * examining the type of the referenced join property. If the type is a Query,

+ * then the internal and external properties are set to match this property's

+ * primary key. The referenced join property (specified as a parameterized type

+ * to Query) must have properties matching name and type of this property's

+ * primary key.

+ * <p>

+ * If a natural join's property type is not defined by a Query, then the

+ * internal and external properties are set to match the referenced property's

+ * primary key. This join property must have properties matching name and type

+ * of the referenced property's primary key.

+ *

+ * <p>Example:<pre>

+ * &#64;PrimaryKey("addressID")

+ * public interface Address extends Storable {

+ *     int getAddressID();

+ *

+ *     ...

+ * }

+ *

+ * &#64;PrimaryKey("userID")

+ * public interface UserInfo extends Storable {

+ *     int getUserID();

+ *

+ *     int getAddressID();

+ *

+ *     void setAddressID(int value);

+ *

+ *     // Natural join, which works because Address has a primary key

+ *     // property of addressID which matches a property in this type.

+ *     <b>&#64;Join</b>

+ *     Address getAddress() throws FetchException;

+ *

+ *     // Explicit join, equivalent to getAddress.

+ *     <b>&#64;Join(internal="addressID", external="addressID")</b>

+ *     Address getCurrentAddress() throws FetchException;

+ *

+ *     &#64;Nullable

+ *     Integer getParentID();

+ *

+ *     void setParentID(Integer value);

+ *

+ *     // Many-to-one relationship

+ *     &#64;Nullable

+ *     <b>&#64;Join(internal="parentID", external="userID")</b>

+ *     UserInfo getParent() throws FetchException;

+ *

+ *     // One-to-many relationship

+ *     <b>&#64;Join(internal="userID", external="parentID")</b>

+ *     Query&lt;UserInfo&gt; getChildren() throws FetchException;

+ *

+ *     ...

+ * }

+ * </pre>

+ *

+ * @author Brian S O'Neill

+ */

+@Documented

+@Retention(RetentionPolicy.RUNTIME)

+@Target({ElementType.METHOD})

+public @interface Join {

+

+    /**

+     * List of property names defined in this property's enclosing class or

+     * interface.

+     */

+    String[] internal() default {};

+

+    /**

+     * List of property names defined in the foreign property's enclosing class

+     * or interface.

+     */

+    String[] external() default {};

+

+}