1/*
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.xml.internal.bind.v2.model.core;
27
28import java.util.Collection;
29import java.util.Set;
30
31import javax.xml.namespace.QName;
32
33/**
34 * {@link PropertyInfo} that holds references to other {@link Element}s.
35 *
36 * @author Kohsuke Kawaguchi
37 */
38public interface ReferencePropertyInfo<T,C> extends PropertyInfo<T,C> {
39    /**
40     * Returns the information about the possible elements in this property.
41     *
42     * <p>
43     * As of 2004/08/17, the spec only allows you to use different element names
44     * when a property is a collection, but I think there's really no reason
45     * to limit it there --- if the user wants to use a different tag name
46     * for different objects, I don't see why this can be limited to collections.
47     *
48     * <p>
49     * So this is a generalization of the spec. We always allow a property to have
50     * multiple types and use different tag names for it, depending on the actual type.
51     *
52     * <p>
53     * In most of the cases, this collection only contains 1 item. So the runtime system
54     * is encouraged to provide a faster code-path that is optimized toward such cases.
55     *
56     * @return
57     *      Always non-null. Contains at least one entry.
58     */
59    Set<? extends Element<T,C>> getElements();
60
61    /**
62     * {@inheritDoc}.
63     *
64     * If this {@link ReferencePropertyInfo} has a wildcard in it,
65     * then the returned list will contain {@link WildcardTypeInfo}.
66     */
67    Collection<? extends TypeInfo<T,C>> ref();
68
69    /**
70     * Gets the wrapper element name.
71     *
72     * @return
73     *      must be null if not collection. If the property is a collection,
74     *      this can be null (in which case there'll be no wrapper),
75     *      or it can be non-null (in which case there'll be a wrapper)
76     */
77    QName getXmlName();
78
79    /**
80     * Returns true if this property is nillable
81     * (meaning the absence of the value is treated as nil='true')
82     *
83     * <p>
84     * This method is only used when this property is a collection.
85     */
86    boolean isCollectionNillable();
87
88    /**
89     * Checks if the wrapper element is required.
90     *
91     * @return
92     *      Always false if {@link #getXmlName()}==null.
93     */
94    boolean isCollectionRequired();
95
96    /**
97     * Returns true if this property can hold {@link String}s to represent
98     * mixed content model.
99     */
100    boolean isMixed();
101
102    /**
103     * If this property supports the wildcard, returns its mode.
104     *
105     * @return null
106     *      if the wildcard is not allowed on this element.
107     */
108    WildcardMode getWildcard();
109
110    /**
111     * If this property supports the wildcard, returns its DOM handler.
112     *
113     * @return null
114     *      if the wildcard is not allowed on this element.
115     */
116    C getDOMHandler();
117
118    /**
119     * Returns true if this element is mandatory.
120     */
121    boolean isRequired();
122
123    Adapter<T,C> getAdapter();
124}
125