001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.util;
033
034 import java.util.Map;
035 import java.util.Set;
036 import org.opengis.annotation.UML;
037
038 import static org.opengis.annotation.Obligation.*;
039 import static org.opengis.annotation.Specification.*;
040
041
042 /**
043 * A list of logically related elements as (<var>name</var>, <var>value</var>) pairs in a
044 * dictionary. A record may be used as an implementation representation for features.
045 *
046 * <p>This class can be think as the equivalent of the Java {@link Object} class.</p>
047 *
048 * @author Bryce Nordgren (USDA)
049 * @author Martin Desruisseaux (IRD)
050 * @version 3.0
051 * @since 2.1
052 *
053 * @see RecordType
054 *
055 * @navassoc 1 - - RecordType
056 */
057 @UML(identifier="Record", specification=ISO_19103)
058 public interface Record {
059 /**
060 * Returns the type definition of record. All attributes named in this record must be defined
061 * in the returned record type. In other words, the following relationship must holds:
062 *
063 * <ul>
064 * <li><code>getRecordType().{@linkplain RecordType#getMembers() getMemberTypes()}.{@linkplain
065 * Set#containsAll containsAll}({@linkplain #getAttributes()}.{@linkplain
066 * Map#keySet keySet()})</code></li>
067 * </ul>
068 *
069 * This method can be think as the equivalent of the Java {@link Object#getClass()} method.
070 *
071 * @return The type definition of this record, or {@code null}.
072 */
073 @UML(identifier="recordType", obligation=OPTIONAL, specification=ISO_19103)
074 RecordType getRecordType();
075
076 /**
077 * Returns the dictionary of all (<var>name</var>, <var>value</var>) pairs in this record.
078 * The returned map shall not allows key addition. It may allows the replacement of values
079 * for existing keys only.
080 *
081 * @return The dictionary of all (<var>name</var>, <var>value</var>) pairs in this record.
082 *
083 * @see RecordType#getMemberTypes()
084 *
085 * @departure generalization
086 * Figure 15 in ISO 19103:2005 specifies a cardinality of 1. However, this seems to
087 * contradict the semantics of the <code>locate(name)</code> and
088 * <code>RecordType.getMemberTypes()</code> methods.
089 */
090 @UML(identifier="memberValue", obligation=MANDATORY, specification=ISO_19103)
091 Map<MemberName, Object> getAttributes();
092
093 /**
094 * Returns the value for an attribute of the specified name. This is functionally equivalent
095 * to <code>{@linkplain #getAttributes()}.{@linkplain Map#get get}(name)</code>.
096 * The type of the returned object is given by
097 * <code>{@linkplain #getRecordType()}.{@linkplain RecordType#getMemberTypes()
098 * getMemberTypes()}.get(name)</code>.
099 *
100 * @param name The name of the attribute to lookup.
101 * @return The value of the attribute for the given name.
102 *
103 * @see RecordType#locate(MemberName)
104 */
105 @UML(identifier="locate", obligation=MANDATORY, specification=ISO_19103)
106 Object locate(MemberName name);
107
108 /**
109 * Sets the value for the attribute of the specified name. This is functionally equivalent
110 * to <code>{@linkplain #getAttributes()}.{@linkplain Map#put put}(name,value)</code>.
111 * Remind that {@code name} keys are constrained to {@linkplain RecordType#getMembers
112 * record type members} only.
113 *
114 * @param name The name of the attribute to modify.
115 * @param value The new value for the attribute.
116 * @throws UnsupportedOperationException if this record is not modifiable.
117 *
118 * @departure easeOfUse
119 * This method provides no additional functionality compared to the ISO standard methods,
120 * but is declared in GeoAPI as a convenient shortcut.
121 */
122 void set(MemberName name, Object value) throws UnsupportedOperationException;
123 }