| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You 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 org.apache.sis.metadata; |
| |
| import java.util.Map; |
| import java.util.Set; |
| import java.util.List; |
| import java.util.EnumMap; |
| import java.util.EnumSet; |
| import java.util.Collection; |
| import java.util.Collections; |
| import java.util.LinkedHashMap; |
| import java.util.Locale; |
| import java.util.Currency; |
| import java.util.NoSuchElementException; |
| import java.lang.reflect.Modifier; |
| import java.nio.charset.Charset; |
| import javax.xml.bind.annotation.XmlTransient; |
| import org.opengis.util.CodeList; |
| import org.apache.sis.util.resources.Errors; |
| import org.apache.sis.util.collection.Containers; |
| import org.apache.sis.util.collection.CodeListSet; |
| import org.apache.sis.internal.util.CollectionsExt; |
| import org.apache.sis.internal.util.CheckedHashSet; |
| import org.apache.sis.internal.util.CheckedArrayList; |
| import org.apache.sis.internal.metadata.Resources; |
| import org.apache.sis.internal.system.Semaphores; |
| |
| import static org.apache.sis.util.collection.Containers.isNullOrEmpty; |
| import static org.apache.sis.internal.metadata.MetadataUtilities.valueIfDefined; |
| |
| |
| /** |
| * Base class of metadata having an editable content. |
| * Newly created {@code ModifiableMetadata} are initially in {@linkplain State#EDITABLE editable} state. |
| * The metadata can be populated using the setter methods provided by subclasses, then transition to the |
| * {@linkplain State#FINAL final} state for making it safe to share by many consumers. |
| * |
| * <h2>Tip for subclass implementations</h2> |
| * Subclasses can follow the pattern below for every {@code get} and {@code set} methods, |
| * with a different processing for singleton value or for {@linkplain Collection collections}. |
| * |
| * {@preformat java |
| * public class MyMetadata { |
| * |
| * // ==== Example for a singleton value ============================= |
| * |
| * private Foo property; |
| * |
| * public Foo getProperty() { |
| * return property; |
| * } |
| * |
| * public void setProperty(Foo newValue) { |
| * checkWritePermission(); |
| * property = newValue; |
| * } |
| * |
| * // ==== Example for a collection ================================== |
| * |
| * private Collection<Foo> properties; |
| * |
| * public Collection<Foo> getProperties() { |
| * return properties = nonNullCollection(properties, Foo.class); |
| * } |
| * |
| * public void setProperties(Collection<Foo> newValues) { |
| * // the call to checkWritePermission() is implicit |
| * properties = writeCollection(newValues, properties, Foo.class); |
| * } |
| * } |
| * } |
| * |
| * @author Martin Desruisseaux (Geomatys) |
| * @version 1.0 |
| * @since 0.3 |
| * @module |
| */ |
| @XmlTransient |
| public abstract class ModifiableMetadata extends AbstractMetadata { |
| /** |
| * The {@link #state} value meaning that the metadata is modifiable. |
| * This is the default state when new {@link ModifiableMetadata} instances are created. |
| */ |
| private static final byte EDITABLE = 0; |
| |
| /** |
| * See https://issues.apache.org/jira/browse/SIS-81 - not yet committed. |
| */ |
| private static final byte STAGED = 1; |
| |
| /** |
| * A value for {@link #state} meaning that execution of {@code transitionTo(…)} is in progress. |
| * Must be greater than all other values except {@link #COMPLETABLE} and {@link #FINAL}. |
| */ |
| private static final byte FREEZING = 2; |
| |
| /** |
| * The {@link #state} value meaning that missing properties can be set, |
| * but no existing properties can be modified (including collections). |
| * This is a kind of semi-final state. |
| */ |
| private static final byte COMPLETABLE = 3; |
| |
| /** |
| * A value for {@link #state} meaning that {@code transitionTo(State.FINAL)} has been invoked. |
| * Must be greater than all other values. |
| */ |
| private static final byte FINAL = 4; |
| |
| /** |
| * Whether this metadata has been made unmodifiable, as one of {@link #EDITABLE}, {@link #FREEZING} |
| * {@link #COMPLETABLE} or {@link #FINAL} values. |
| * |
| * <p>This field is not yet serialized because we are not sure to keep this information as a byte in |
| * the future. We could for example use an {@code int} and use remaining bits for caching hash-code |
| * value of final metadata.</p> |
| */ |
| private transient byte state; |
| |
| /** |
| * Constructs an initially empty metadata. |
| * The initial state is {@link State#EDITABLE}. |
| */ |
| protected ModifiableMetadata() { |
| } |
| |
| /** |
| * Whether the metadata is still editable or has been made final. |
| * New {@link ModifiableMetadata} instances are initially {@link #EDITABLE} |
| * and can be made {@link #FINAL} after construction by a call to {@link ModifiableMetadata#transitionTo(State)}. |
| * |
| * <div class="note"><b>Note:</b> |
| * more states may be added in future Apache SIS versions. On possible candidate is {@code STAGED}. |
| * See <a href="https://issues.apache.org/jira/browse/SIS-81">SIS-81</a>.</div> |
| * |
| * @author Martin Desruisseaux (Geomatys) |
| * @version 1.0 |
| * @since 1.0 |
| * @module |
| */ |
| public enum State { |
| /** |
| * The metadata is modifiable. |
| * This is the default state when new {@link ModifiableMetadata} instances are created. |
| * Note that a modifiable metadata instance does <strong>not</strong> imply that all |
| * properties contained in that instance are also editable. |
| */ |
| EDITABLE(ModifiableMetadata.EDITABLE), |
| |
| /** |
| * The metadata allows missing values to be set, but does not allow existing values to be modified. |
| * This state is not appendable, i.e. it does not allow adding elements in a collection. |
| */ |
| COMPLETABLE(ModifiableMetadata.COMPLETABLE), |
| |
| /** |
| * The metadata is unmodifiable. |
| * When a metadata is final, it can not be moved back to an editable state |
| * (but it is still possible to create a modifiable copy with {@link MetadataCopier}). |
| * Invoking any setter method on an unmodifiable metadata cause an |
| * {@link UnmodifiableMetadataException} to be thrown. |
| */ |
| FINAL(ModifiableMetadata.FINAL); |
| |
| /** |
| * Mapping from {@link ModifiableMetadata} private flags to {@code State} enumeration. |
| * A mapping exists because {@code ModifiableMetadata} does not use the same set of enumeration values |
| * (e.g. it has an internal {@link #FREEZING} value), and because future versions may use a bitmask. |
| */ |
| private static final State[] VALUES = new State[ModifiableMetadata.FINAL + 1]; |
| static { |
| VALUES[ModifiableMetadata.EDITABLE] = EDITABLE; |
| VALUES[ModifiableMetadata.STAGED] = EDITABLE; |
| VALUES[ModifiableMetadata.FREEZING] = FINAL; |
| VALUES[ModifiableMetadata.COMPLETABLE] = COMPLETABLE; |
| VALUES[ModifiableMetadata.FINAL] = FINAL; |
| } |
| |
| /** |
| * The numerical code associated to this enumeration value. It serves similar purpose to the |
| * {@link #ordinal()} value, but is nevertheless provided for the reasons given in {@link #VALUES}. |
| */ |
| final byte code; |
| |
| /** |
| * Creates a new state associated to the given code numerical code. |
| */ |
| private State(final byte code) { |
| this.code = code; |
| } |
| } |
| |
| /** |
| * Tells whether this instance of metadata is editable. |
| * This is initially {@link State#EDITABLE} for new {@code ModifiableMetadata} instances, |
| * but can be changed by a call to {@link #transitionTo(State)}. |
| * |
| * <p>{@link State#FINAL} implies that all properties are also final. |
| * This recursivity does not necessarily apply to other states. For example {@link State#EDITABLE} |
| * does <strong>not</strong> imply that all {@code ModifiableMetadata} children are also editable.</p> |
| * |
| * <div class="note"><b>API note:</b> |
| * the {@code ModifiableMetadata} state is not a metadata per se, but rather an information about |
| * this particular instance of a metadata class. Two metadata instances may be in different states |
| * but still have the same metadata content. For this reason, this method does not have {@code get} |
| * prefix for avoiding confusion with getter and setter methods of metadata properties.</div> |
| * |
| * @return the state (editable, completable or final) of this {@code ModifiableMetadata} instance. |
| * |
| * @since 1.0 |
| */ |
| public State state() { |
| return State.VALUES[state]; |
| } |
| |
| /** |
| * Requests this metadata instance and (potentially) all its children to transition to a new state. |
| * The action performed by this method depends on the {@linkplain #state() source state} and the |
| * given target state, as listed in the following table: |
| * |
| * <table class="sis"> |
| * <caption>State transitions</caption> |
| * <tr> |
| * <th>Current state</th> |
| * <th>Target state</th> |
| * <th>Action</th> |
| * </tr><tr> |
| * <td><var>Any</var></td> |
| * <td><var>Same</var></td> |
| * <td>Does nothing and returns {@code false}.</td> |
| * </tr><tr> |
| * <td>{@link State#EDITABLE}</td> |
| * <td>{@link State#COMPLETABLE}</td> |
| * <td>Marks this metadata and all children as completable.</td> |
| * </tr><tr> |
| * <td>Any</td> |
| * <td>{@link State#FINAL}</td> |
| * <td>Marks this metadata and all children as unmodifiable.</td> |
| * </tr><tr> |
| * <td>{@link State#FINAL}</td> |
| * <td>Any other</td> |
| * <td>Throws {@link UnmodifiableMetadataException}.</td> |
| * </tr> |
| * </table> |
| * |
| * The effect of invoking this method may be recursive. For example transitioning to {@link State#FINAL} |
| * implies transitioning all children {@code ModifiableMetadata} instances to the final state too. |
| * |
| * @param target the desired new state. |
| * @return {@code true} if the state of this {@code ModifiableMetadata} changed as a result of this method call. |
| * @throws UnmodifiableMetadataException if a transition to a less restrictive state |
| * (e.g. from {@link State#FINAL} to {@link State#EDITABLE}) was attempted. |
| * |
| * @since 1.0 |
| */ |
| public boolean transitionTo(final State target) { |
| if (target.code < state) { |
| throw new UnmodifiableMetadataException(Resources.format(Resources.Keys.UnmodifiableMetadata)); |
| } |
| if (target.code == state || state == FREEZING) { |
| return false; |
| } |
| byte result = state; |
| try { |
| state = FREEZING; |
| StateChanger.applyTo(target, this); |
| result = target.code; |
| } finally { |
| state = result; |
| } |
| return true; |
| } |
| |
| /** |
| * Checks if changes in the metadata are allowed. All {@code setFoo(…)} methods in subclasses |
| * shall invoke this method (directly or indirectly) before to apply any change. |
| * The current property value should be specified in argument. |
| * |
| * @param current the current value, or {@code null} if none. |
| * @throws UnmodifiableMetadataException if this metadata is unmodifiable. |
| * |
| * @see #state() |
| * |
| * @since 1.0 |
| */ |
| protected void checkWritePermission(Object current) throws UnmodifiableMetadataException { |
| if (state != COMPLETABLE) { |
| if (state == FINAL) { |
| throw new UnmodifiableMetadataException(Resources.format(Resources.Keys.UnmodifiableMetadata)); |
| } |
| } else if (current != null) { |
| final MetadataStandard standard; |
| if (current instanceof AbstractMetadata) { |
| standard = ((AbstractMetadata) current).getStandard(); |
| } else { |
| standard = getStandard(); |
| } |
| final Object c = standard.getTitle(current); |
| if (c != null) current = c; |
| throw new UnmodifiableMetadataException(Resources.format(Resources.Keys.ElementAlreadyInitialized_1, current)); |
| } |
| } |
| |
| /** |
| * Writes the content of the {@code source} collection into the {@code target} list, |
| * creating it if needed. This method performs the following steps: |
| * |
| * <ul> |
| * <li>Invokes {@link #checkWritePermission(Object)} in order to ensure that this metadata is modifiable.</li> |
| * <li>If {@code source} is null or empty, returns {@code null} |
| * (meaning that the metadata property is not provided).</li> |
| * <li>If {@code target} is null, creates a new {@link List}.</li> |
| * <li>Copies the content of the given {@code source} into the target.</li> |
| * </ul> |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source list, or {@code null}. |
| * @param target the target list, or {@code null} if not yet created. |
| * @param elementType the base type of elements to put in the list. |
| * @return a list (possibly the {@code target} instance) containing the {@code source} |
| * elements, or {@code null} if the source was null. |
| * @throws UnmodifiableMetadataException if this metadata is unmodifiable. |
| * |
| * @see #nonNullList(List, Class) |
| */ |
| @SuppressWarnings("unchecked") |
| protected final <E> List<E> writeList(Collection<? extends E> source, List<E> target, |
| Class<E> elementType) throws UnmodifiableMetadataException |
| { |
| return (List<E>) write(source, target, elementType, Boolean.FALSE); |
| } |
| |
| /** |
| * Writes the content of the {@code source} collection into the {@code target} set, |
| * creating it if needed. This method performs the following steps: |
| * |
| * <ul> |
| * <li>Invokes {@link #checkWritePermission(Object)} in order to ensure that this metadata is modifiable.</li> |
| * <li>If {@code source} is null or empty, returns {@code null} |
| * (meaning that the metadata property is not provided).</li> |
| * <li>If {@code target} is null, creates a new {@link Set}.</li> |
| * <li>Copies the content of the given {@code source} into the target.</li> |
| * </ul> |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source set, or {@code null}. |
| * @param target the target set, or {@code null} if not yet created. |
| * @param elementType the base type of elements to put in the set. |
| * @return a set (possibly the {@code target} instance) containing the {@code source} elements, |
| * or {@code null} if the source was null. |
| * @throws UnmodifiableMetadataException if this metadata is unmodifiable. |
| * |
| * @see #nonNullSet(Set, Class) |
| */ |
| protected final <E> Set<E> writeSet(Collection<? extends E> source, Set<E> target, |
| Class<E> elementType) throws UnmodifiableMetadataException |
| { |
| return (Set<E>) write(source, target, elementType, Boolean.TRUE); |
| } |
| |
| /** |
| * Writes the content of the {@code source} collection into the {@code target} list or set, |
| * creating it if needed. This method performs the following steps: |
| * |
| * <ul> |
| * <li>Invokes {@link #checkWritePermission(Object)} in order to ensure that this metadata is modifiable.</li> |
| * <li>If {@code source} is null or empty, returns {@code null} |
| * (meaning that the metadata property is not provided).</li> |
| * <li>If {@code target} is null, creates a new {@link Set} or a new {@link List} |
| * depending on the value returned by {@link #collectionType(Class)}.</li> |
| * <li>Copies the content of the given {@code source} into the target.</li> |
| * </ul> |
| * |
| * <h4>Choosing a collection type</h4> |
| * Implementations shall invoke {@link #writeList writeList} or {@link #writeSet writeSet} methods |
| * instead than this method when the collection type is enforced by ISO specification. |
| * When the type is not enforced by the specification, some freedom are allowed at |
| * implementer choice. The default implementation invokes {@link #collectionType(Class)} |
| * in order to get a hint about whether a {@link List} or a {@link Set} should be used. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source collection, or {@code null}. |
| * @param target the target collection, or {@code null} if not yet created. |
| * @param elementType the base type of elements to put in the collection. |
| * @return a collection (possibly the {@code target} instance) containing the {@code source} elements, |
| * or {@code null} if the source was null. |
| * @throws UnmodifiableMetadataException if this metadata is unmodifiable. |
| */ |
| protected final <E> Collection<E> writeCollection(Collection<? extends E> source, Collection<E> target, |
| Class<E> elementType) throws UnmodifiableMetadataException |
| { |
| return write(source, target, elementType, null); |
| } |
| |
| /** |
| * Writes the content of the {@code source} collection into the {@code target} list or set, |
| * creating it if needed. |
| * |
| * @param useSet {@link Boolean#TRUE} for creating a set, {@link Boolean#FALSE} for creating a list, |
| * or null for automatic choice. |
| */ |
| @SuppressWarnings("unchecked") |
| private <E> Collection<E> write(final Collection<? extends E> source, Collection<E> target, |
| final Class<E> elementType, Boolean useSet) throws UnmodifiableMetadataException |
| { |
| /* |
| * It is not worth to copy the content if the current and the new instance are the |
| * same. This is safe only using the != operator, not the !equals(Object) method. |
| * This optimization is required for efficient working of PropertyAccessor.set(…) |
| * and JAXB unmarshalling. |
| */ |
| if (source != target) { |
| if (state == FREEZING) { |
| /* |
| * transitionTo(State.FINAL) is under progress. The source collection is already |
| * an unmodifiable instance created by StateChanger. |
| */ |
| assert (useSet != null) || collectionType(elementType).isInstance(source) : elementType; |
| return (Collection<E>) source; |
| } |
| checkWritePermission(valueIfDefined(target)); |
| if (isNullOrEmpty(source)) { |
| target = null; |
| } else { |
| /* |
| * Reuse the existing collection if available, except in State.COMPLETABLE case |
| * since that collection may the Collection.EMPTY_SET or EMPTY_LIST. |
| */ |
| if (target != null && state != COMPLETABLE) { |
| target.clear(); |
| } else { |
| if (useSet == null) { |
| useSet = useSet(elementType); |
| } |
| if (useSet) { |
| target = createSet(elementType, source); |
| } else { |
| target = createList(elementType, source); |
| } |
| } |
| target.addAll(source); |
| if (state == COMPLETABLE) { |
| if (useSet) { |
| target = CollectionsExt.unmodifiableOrCopy((Set<E>) target); |
| } else { |
| target = CollectionsExt.unmodifiableOrCopy((List<E>) target); |
| } |
| } |
| } |
| } |
| return target; |
| } |
| |
| /** |
| * Writes the content of the {@code source} map into the {@code target} map, |
| * creating it if needed. This method performs the following steps: |
| * |
| * <ul> |
| * <li>Invokes {@link #checkWritePermission(Object)} in order to ensure that this metadata is modifiable.</li> |
| * <li>If {@code source} is null or empty, returns {@code null} |
| * (meaning that the metadata property is not provided).</li> |
| * <li>If {@code target} is null, creates a new {@link Map}.</li> |
| * <li>Copies the content of the given {@code source} into the target.</li> |
| * </ul> |
| * |
| * @param <K> the type of keys represented by the {@code Class} argument. |
| * @param <V> the type of values in the map. |
| * @param source the source map, or {@code null}. |
| * @param target the target map, or {@code null} if not yet created. |
| * @param keyType the base type of keys to put in the map. |
| * @return a map (possibly the {@code target} instance) containing the {@code source} entries, |
| * or {@code null} if the source was null. |
| * @throws UnmodifiableMetadataException if this metadata is unmodifiable. |
| * |
| * @see #nonNullMap(Map, Class) |
| * |
| * @since 1.0 |
| */ |
| @SuppressWarnings("unchecked") |
| protected final <K,V> Map<K,V> writeMap(final Map<? extends K, ? extends V> source, Map<K,V> target, |
| Class<K> keyType) throws UnmodifiableMetadataException |
| { |
| /* |
| * Code in this method is a copy of write(Collection, Collection, Class) with some calls inlined. |
| * See the comments inside that write(…) method body for more information on the logic. |
| */ |
| if (source != target) { |
| if (state == FREEZING) { |
| return (Map<K,V>) source; |
| } |
| checkWritePermission((target == null) || target.isEmpty() ? null : target); |
| if (isNullOrEmpty(source)) { |
| target = null; |
| } else { |
| if (target != null && state != COMPLETABLE) { |
| target.clear(); |
| } else { |
| target = createMap(keyType, source); |
| } |
| target.putAll(source); |
| if (state == COMPLETABLE) { |
| target = CollectionsExt.unmodifiableOrCopy(target); |
| } |
| } |
| } |
| return target; |
| } |
| |
| /** |
| * Creates a list with the content of the {@code source} collection, |
| * or returns {@code null} if the source is {@code null} or empty. |
| * This is a convenience method for copying fields in subclass copy constructors. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source collection, or {@code null}. |
| * @param elementType the base type of elements to put in the list. |
| * @return a list containing the {@code source} elements, |
| * or {@code null} if the source was null or empty. |
| */ |
| protected final <E> List<E> copyList(final Collection<? extends E> source, final Class<E> elementType) { |
| if (isNullOrEmpty(source)) { |
| return null; |
| } |
| final List<E> target = createList(elementType, source); |
| target.addAll(source); |
| return target; |
| } |
| |
| /** |
| * Creates a set with the content of the {@code source} collection, |
| * or returns {@code null} if the source is {@code null} or empty. |
| * This is a convenience method for copying fields in subclass copy constructors. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source collection, or {@code null}. |
| * @param elementType the base type of elements to put in the set. |
| * @return a set containing the {@code source} elements, |
| * or {@code null} if the source was null or empty. |
| */ |
| protected final <E> Set<E> copySet(final Collection<? extends E> source, final Class<E> elementType) { |
| if (isNullOrEmpty(source)) { |
| return null; |
| } |
| final Set<E> target = createSet(elementType, source); |
| target.addAll(source); |
| return target; |
| } |
| |
| /** |
| * Creates a list or set with the content of the {@code source} collection, |
| * or returns {@code null} if the source is {@code null} or empty. |
| * This is a convenience method for copying fields in subclass copy constructors. |
| * |
| * <p>The collection type is selected as described in the |
| * {@link #nonNullCollection(Collection, Class)}.</p> |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param source the source collection, or {@code null}. |
| * @param elementType the base type of elements to put in the collection. |
| * @return a collection containing the {@code source} elements, |
| * or {@code null} if the source was null or empty. |
| */ |
| protected final <E> Collection<E> copyCollection(final Collection<? extends E> source, final Class<E> elementType) { |
| if (isNullOrEmpty(source)) { |
| return null; |
| } |
| final Collection<E> target; |
| if (useSet(elementType)) { |
| target = createSet(elementType, source); |
| } else { |
| target = createList(elementType, source); |
| } |
| target.addAll(source); |
| return target; |
| } |
| |
| /** |
| * Creates a map with the content of the {@code source} map, |
| * or returns {@code null} if the source is {@code null} or empty. |
| * This is a convenience method for copying fields in subclass copy constructors. |
| * |
| * @param <K> the type of keys represented by the {@code Class} argument. |
| * @param <V> the type of values in the map. |
| * @param source the source map, or {@code null}. |
| * @param keyType the base type of keys to put in the map. |
| * @return a map containing the {@code source} entries, |
| * or {@code null} if the source was null or empty. |
| * |
| * @since 1.0 |
| */ |
| protected final <K,V> Map<K,V> copyMap(final Map<? extends K, ? extends V> source, final Class<K> keyType) { |
| if (isNullOrEmpty(source)) { |
| return null; |
| } |
| final Map<K,V> target = createMap(keyType, source); |
| target.putAll(source); |
| return target; |
| } |
| |
| /** |
| * Creates a singleton list or set containing only the given value, if non-null. |
| * This is a convenience method for initializing fields in subclass constructors. |
| * |
| * <p>The collection type is selected as described in the |
| * {@link #nonNullCollection(Collection, Class)}.</p> |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param value the singleton value to put in the returned collection, or {@code null}. |
| * @param elementType the element type (used only if {@code value} is non-null). |
| * @return a new modifiable collection containing the given value, |
| * or {@code null} if the given value was null. |
| */ |
| protected final <E> Collection<E> singleton(final E value, final Class<E> elementType) { |
| if (value == null) { |
| return null; |
| } |
| final Collection<E> collection; |
| if (useSet(elementType)) { |
| collection = createSet(elementType, null); |
| } else { |
| collection = new CheckedArrayList<>(elementType, 1); |
| } |
| collection.add(value); |
| return collection; |
| } |
| |
| /** |
| * Returns {@code true} if empty collection should be returned as {@code null} value. |
| * This is usually not a behavior that we allow in public API. However this behavior |
| * is sometime desired internally, for example when marshalling with JAXB or when |
| * performing a {@code equals}, {@code isEmpty} or {@code prune} operation |
| * (for avoiding creating unnecessary collections). |
| */ |
| private static boolean emptyCollectionAsNull() { |
| return Semaphores.query(Semaphores.NULL_COLLECTION); |
| } |
| |
| /** |
| * Returns the specified list, or a new one if {@code current} is null. |
| * This is a convenience method for implementation of {@code getFoo()} methods. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param current the existing list, or {@code null} if the list has not yet been created. |
| * @param elementType the element type (used only if {@code current} is null). |
| * @return {@code current}, or a new list if {@code current} is null. |
| */ |
| protected final <E> List<E> nonNullList(final List<E> current, final Class<E> elementType) { |
| if (current != null) { |
| return current.isEmpty() && emptyCollectionAsNull() ? null : current; |
| } |
| if (emptyCollectionAsNull()) { |
| return null; |
| } |
| if (state < FREEZING) { |
| return createList(elementType, current); // `current` given as a matter of principle even if null. |
| } |
| return Collections.emptyList(); |
| } |
| |
| /** |
| * Returns the specified set, or a new one if {@code current} is null. |
| * This is a convenience method for implementation of {@code getFoo()} methods. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param current the existing set, or {@code null} if the set has not yet been created. |
| * @param elementType the element type (used only if {@code current} is null). |
| * @return {@code current}, or a new set if {@code current} is null. |
| */ |
| protected final <E> Set<E> nonNullSet(final Set<E> current, final Class<E> elementType) { |
| if (current != null) { |
| return current.isEmpty() && emptyCollectionAsNull() ? null : current; |
| } |
| if (emptyCollectionAsNull()) { |
| return null; |
| } |
| if (state < FREEZING) { |
| return createSet(elementType, current); // `current` given as a matter of principle even if null. |
| } |
| return Collections.emptySet(); |
| } |
| |
| /** |
| * Returns the specified collection, or a new one if {@code current} is null. |
| * This is a convenience method for implementation of {@code getFoo()} methods. |
| * |
| * <h4>Choosing a collection type</h4> |
| * Implementations shall invoke {@link #nonNullList nonNullList(…)} or {@link #nonNullSet nonNullSet(…)} |
| * instead than this method when the collection type is enforced by ISO specification. |
| * When the type is not enforced by the specification, some freedom are allowed at implementer choice. |
| * The default implementation invokes {@link #collectionType(Class)} in order to get a hint about whether |
| * a {@link List} or a {@link Set} should be used. |
| * |
| * @param <E> the type represented by the {@code Class} argument. |
| * @param current the existing collection, or {@code null} if the collection has not yet been created. |
| * @param elementType the element type (used only if {@code current} is null). |
| * @return {@code current}, or a new collection if {@code current} is null. |
| */ |
| protected final <E> Collection<E> nonNullCollection(final Collection<E> current, final Class<E> elementType) { |
| if (current != null) { |
| assert collectionType(elementType).isInstance(current); |
| return current.isEmpty() && emptyCollectionAsNull() ? null : current; |
| } |
| if (emptyCollectionAsNull()) { |
| return null; |
| } |
| final boolean isModifiable = (state < FREEZING); |
| if (useSet(elementType)) { |
| if (isModifiable) { |
| return createSet(elementType, current); // `current` given as a matter of principle even if null. |
| } else { |
| return Collections.emptySet(); |
| } |
| } else { |
| if (isModifiable) { |
| return createList(elementType, current); // `current` given as a matter of principle even if null. |
| } else { |
| return Collections.emptyList(); |
| } |
| } |
| } |
| |
| /** |
| * Returns the specified map, or a new one if {@code current} is null. |
| * This is a convenience method for implementation of {@code getFoo()} methods. |
| * |
| * @param <K> the type of keys represented by the {@code Class} argument. |
| * @param <V> the type of values in the map. |
| * @param current the existing map, or {@code null} if the map has not yet been created. |
| * @param keyType the key type (used only if {@code current} is null). |
| * @return {@code current}, or a new map if {@code current} is null. |
| * |
| * @since 1.0 |
| */ |
| protected final <K,V> Map<K,V> nonNullMap(final Map<K,V> current, final Class<K> keyType) { |
| if (current != null) { |
| return current.isEmpty() && emptyCollectionAsNull() ? null : current; |
| } |
| if (emptyCollectionAsNull()) { |
| return null; |
| } |
| if (state < FREEZING) { |
| return createMap(keyType, current); // `current` given as a matter of principle even if null. |
| } |
| return Collections.emptyMap(); |
| } |
| |
| /** |
| * Creates a modifiable list for elements of the given type. This method is defined mostly |
| * for consistency with {@link #createSet(Class, Collection)}. |
| * |
| * @param source the collection to be copied in the new list. This method uses this information |
| * only for computing initial capacity; it does not perform the actual copy. |
| */ |
| private static <E> List<E> createList(final Class<E> elementType, final Collection<?> source) { |
| if (source == null) { |
| /* |
| * Do not specify an initial capacity, because the list will stay empty in a majority of cases |
| * (i.e. the users will want to iterate over the list elements more often than they will want |
| * to add elements). JDK implementation of ArrayList has a lazy instantiation mechanism for |
| * initially empty lists, but as of JDK 10 this lazy instantiation works only for list having |
| * the default capacity. |
| */ |
| return new CheckedArrayList<>(elementType); |
| } |
| return new CheckedArrayList<>(elementType, source.size()); |
| } |
| |
| /** |
| * Creates a modifiable set for elements of the given type. This method will create an {@link EnumSet}, |
| * {@link CodeListSet} or {@link java.util.LinkedHashSet} depending on the {@code elementType} argument. |
| * The set must have a stable iteration order (this is needed by {@link TreeTableView}). |
| * |
| * @param source the collection to be copied in the new set, or {@code null} if unknown. |
| * This method uses this information only for computing initial capacity; |
| * it does not perform the actual copy. |
| */ |
| @SuppressWarnings({"unchecked","rawtypes"}) |
| private static <E> Set<E> createSet(final Class<E> elementType, final Collection<?> source) { |
| if (Enum.class.isAssignableFrom(elementType)) { |
| return EnumSet.noneOf((Class) elementType); |
| } |
| if (CodeList.class.isAssignableFrom(elementType) && Modifier.isFinal(elementType.getModifiers())) { |
| return new CodeListSet(elementType); |
| } |
| /* |
| * If we can not compute an initial capacity from the size of an existing source, use an arbitrary |
| * small value (currently 4). We use a small value because collections will typically contain few |
| * elements (often just a singleton). |
| */ |
| return new CheckedHashSet<>(elementType, (source != null) ? Containers.hashMapCapacity(source.size()) : 4); |
| } |
| |
| /** |
| * Creates a modifiable map for elements of the given type. |
| * The map must have a stable iteration order (this is needed by {@link TreeTableView}). |
| * |
| * @param source the map to be copied in the new map. This method uses this information |
| * only for computing initial capacity; it does not perform the actual copy. |
| */ |
| @SuppressWarnings({"unchecked","rawtypes"}) |
| private static <K,V> Map<K,V> createMap(final Class<K> keyType, final Map<?,?> source) { |
| if (Enum.class.isAssignableFrom(keyType)) { |
| return new EnumMap(keyType); |
| } else { |
| // Must be LinkedHashMap, not HashMap, because TreeTableView needs stable iteration order. |
| return new LinkedHashMap<>((source != null) ? Containers.hashMapCapacity(source.size()) : 4); |
| } |
| } |
| |
| /** |
| * Returns {@code true} if we should use a {@link Set} instead than a {@link List} |
| * for elements of the given type. |
| */ |
| private <E> boolean useSet(final Class<E> elementType) { |
| final Class<? extends Collection<E>> type = collectionType(elementType); |
| if (Set .class == (Class) type) return true; |
| if (List.class == (Class) type) return false; |
| throw new NoSuchElementException(Errors.format(Errors.Keys.UnsupportedType_1, type)); |
| } |
| |
| /** |
| * Returns the type of collection to use for the given type. The current implementation can |
| * return only two values: <code>{@linkplain Set}.class</code> if the property should not |
| * accept duplicated values, or <code>{@linkplain List}.class</code> otherwise. Future SIS |
| * versions may accept other types. |
| * |
| * <p>The default implementation returns <code>{@linkplain Set}.class</code> if the element type |
| * is assignable to {@link CodeList}, {@link Enum}, {@link String}, {@link Charset}, |
| * {@link Locale} or {@link Currency}, and <code>{@linkplain List}.class</code> otherwise. |
| * Subclasses can override this method for choosing different kind of collections. |
| * <em>Note however that {@link Set} should be used only with immutable element types</em>, |
| * for {@linkplain Object#hashCode() hash code} stability.</p> |
| * |
| * @param <E> the type of elements in the collection to be created. |
| * @param elementType the type of elements in the collection to be created. |
| * @return {@code List.class} or {@code Set.class} depending on whether the |
| * property shall accept duplicated values or not. |
| */ |
| @SuppressWarnings({"rawtypes","unchecked"}) |
| protected <E> Class<? extends Collection<E>> collectionType(final Class<E> elementType) { |
| return (Class) (CodeList.class.isAssignableFrom(elementType) |
| || Enum.class.isAssignableFrom(elementType) |
| || Charset.class.isAssignableFrom(elementType) |
| || String.class == elementType |
| || Locale.class == elementType |
| || Currency.class == elementType |
| ? Set.class : List.class); |
| } |
| } |
