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 
  26 package com.sun.xml.internal.bind.v2.model.core;
  27 
  28 import java.util.Collection;
  29 import java.util.Set;
  30 
  31 import javax.xml.namespace.QName;
  32 
  33 /**
  34  * {@link PropertyInfo} that holds references to other {@link Element}s.
  35  *
  36  * @author Kohsuke Kawaguchi
  37  */
  38 public 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 }