001: /*
002: * $Header: /export/home/cvsroot/MyPersonalizerRepository/MyPersonalizer/Subsystems/Kernel/Sources/es/udc/mypersonalizer/kernel/model/metainfo/MetaProperty.java,v 1.1.1.1 2004/03/25 12:08:37 fbellas Exp $
003: * $Revision: 1.1.1.1 $
004: * $Date: 2004/03/25 12:08:37 $
005: *
006: * =============================================================================
007: *
008: * Copyright (c) 2003, The MyPersonalizer Development Group
009: * (http://www.tic.udc.es/~fbellas/mypersonalizer/index.html) at
010: * University Of A Coruna
011: * All rights reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions are met:
015: *
016: * - Redistributions of source code must retain the above copyright notice,
017: * this list of conditions and the following disclaimer.
018: *
019: * - Redistributions in binary form must reproduce the above copyright notice,
020: * this list of conditions and the following disclaimer in the documentation
021: * and/or other materials provided with the distribution.
022: *
023: * - Neither the name of the University Of A Coruna nor the names of its
024: * contributors may be used to endorse or promote products derived from
025: * this software without specific prior written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
028: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
029: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
030: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
031: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
032: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
033: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
034: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
035: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
036: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
037: * POSSIBILITY OF SUCH DAMAGE.
038: *
039: */
040:
041: package es.udc.mypersonalizer.kernel.model.metainfo;
042:
043: import java.util.Iterator;
044:
045: import es.udc.mypersonalizer.kernel.model.annotators.AnnotatedObject;
046: import es.udc.mypersonalizer.kernel.model.annotators.Annotations;
047: import es.udc.mypersonalizer.kernel.util.exceptions.VisitorException;
048:
049: /**
050: * Defines common operations to all <code>MetaProperty</code> implementations
051: * and represents a meta-description of a
052: * {@link es.udc.mypersonalizer.kernel.model.properties.Property}
053: * structure.
054: * <p>
055: * <code>MetaProperty</code> corresponds to the "Component" participant
056: * in the "Composite" pattern, that is, the root interface declaring all
057: * common operations to derived classes/interfaces. Concrete implementations
058: * will either be leaf or composite classes.
059: * <p>
060: * This structure is homonymous of the property structure described by
061: * {@link es.udc.mypersonalizer.kernel.model.properties.Property}.
062: * It also includes information that can be interesting to other parts of
063: * the "MyPersonalizer" framework, such as the persistence system.
064: * <p>
065: * To give an example, consider the example of the property used in the
066: * personalizable news service, described in the documentation of the
067: * {@link es.udc.mypersonalizer.kernel.model.properties.Property}
068: * interface. Such a property could be represented by a meta-property composed
069: * of two simple meta-properties. The compound meta-property represents the
070: * compound property "newServiceProperties", and the simple meta-properties
071: * represent the simple properties "numberOfHeadlines" and "sources". The
072: * three meta-properties give information (for example, simple name, Java
073: * type, whether or not is multivalued, so on) on its corresponding
074: * properties.
075: * <p>
076: * Note that, except for simple names, the naming system needs to be
077: * different from that of <code>Property</code>s. So, the full names of the
078: * two simple meta-properties of the above example are
079: * "newsServiceProperties.numberOfHeadlines" and
080: * "newsServiceProperties.sources". That is, indexes are not used, because
081: * there is no need to have a meta-structure parallel to
082: * <code>PropertyStructure</code>.
083: * <p>
084: * Like <code>Property</code>s, mame resolution, finding a meta-property
085: * from another one, is always relative to the second one. So, for example,
086: * considering the above example, if you want to refer to the meta-property
087: * "sources", you must use the relative name "sources" when looking for such
088: * a meta-property from the root meta-property ("newsServiceProperties").
089: *
090: * @author Fernando Bellas
091: * @author Abel Muinho
092: * @see es.udc.mypersonalizer.kernel.model.properties.Property
093: * @since 1.0
094: */
095: public interface MetaProperty extends java.io.Serializable,
096: AnnotatedObject {
097:
098: /**
099: * Defines common operations to all <code>MetaPropertyVisitor</code>s
100: * implementations and represents a way to perform operations on the
101: * objects of a <code>MetaProperty</code> structure, depending on their
102: * concrete classes.
103: * <p>
104: * <code>Visitor</code> corresponds to the "Visitor" participant
105: * in the "Visitor" pattern, that is, an interface declaring all common
106: * operations to derived classes.
107: * <p>
108: * This pattern is used to go through the <code>Property</code>
109: * structure. It is responsability of this pattern for the process
110: * of traversing such structure. So the programmer must take this into
111: * account in order to develop a Visitor to perform an operation over
112: * this hierarchical construction.
113: */
114: public interface Visitor {
115: /**
116: * Visit operation for a <code>MetaSimpleProperty</code>.
117: *
118: * @param metaProperty the <code>MetaSimpleProperty</code>
119: * object over which the visitor can operate.
120: *
121: * @return an <code>Object</code> of needful for the caller.
122: * This is specially interesting for traverse of "Composite"
123: * structures. May be a <code>null</code> value
124: * @throws VisitorException if an internal error occurs while
125: * processing the visited object
126: */
127: Object visitMetaSimpleProperty(MetaSimpleProperty metaProperty)
128: throws VisitorException;
129:
130: /**
131: * Visit operation for a <code>MetaCompoundProperty</code>.
132: *
133: * @param metaProperty the <code>MetaCompoundProperty</code>
134: * object over which the visitor can operate.
135: *
136: * @return an <code>Object</code> of needful for the caller.
137: * This is specially interesting for traverse of "Composite"
138: * structures. May be a <code>null</code> value
139: * @throws VisitorException if an internal error occurs while
140: * processing the visited object
141: */
142: Object visitMetaCompoundProperty(
143: MetaCompoundProperty metaProperty)
144: throws VisitorException;
145: }
146:
147: /**
148: * Returns the simple name of the meta-property.
149: *
150: * @return the simple name of the meta-property
151: */
152: String getSimpleName();
153:
154: /**
155: * Sets the simple name for the property represented by
156: * this meta-property.
157: *
158: * @param simpleName the simple name for the property
159: * represented by this meta-property
160: */
161: void setSimpleName(String simpleName);
162:
163: /**
164: * Returns whether the property represented by this meta-property
165: * is multivalued or not.
166: *
167: * @return whether the property represented by this meta-property
168: * is multivalued or not
169: */
170: boolean isMultiValued();
171:
172: /**
173: * Sets the multivalued attribute for the property represented
174: * by this meta-property.
175: *
176: * @param multiValued the multivalued attribute. <code>true</code>
177: * specifies a property which can hold multiple values
178: */
179: void setMultiValued(boolean multiValued);
180:
181: /**
182: * Returns the meta-properties that compounds this meta-property
183: * as an Iterator.
184: *
185: * @return the meta-properties that compounds this meta-property
186: * as an Iterator
187: * @throws java.lang.UnsupportedOperationException if the operation
188: * is not supported by this meta-property
189: */
190: Iterator getMetaProperties();
191:
192: /**
193: * Adds a <code>MetaProperty</code> to the collection of
194: * meta-properties of a compound meta-property.
195: *
196: * @param metaProperty the <code>MetaProperty</code> to be added to
197: * the meta-properties that compounds this one.
198: * @throws java.lang.UnsupportedOperationException if the operation
199: * is not supported by this meta-property
200: */
201: void addMetaProperty(MetaProperty metaProperty);
202:
203: /**
204: * Returns the meta-property specified by the relative name
205: * <code>relativeName</code>.
206: * <p>
207: * If the relative name passed as a parameter is <code>""</code>, the
208: * method returns this same meta-property.
209: *
210: * @param relativeName the relative name of the meta-property
211: * @return the named meta-property
212: * @throws java.lang.UnsupportedOperationException if the operation is not
213: * supported by this meta-property
214: * @throws MetaPropertyNotFoundException if there not exist a
215: * meta-property with this name
216: */
217: MetaProperty findMetaProperty(String relativeName)
218: throws MetaPropertyNotFoundException;
219:
220: /**
221: * Operation which allows this object to <b>accept</b> a visitor
222: * to perform an operation over it.
223: * It's the Accept operation implementation for the "Visitor" pattern.
224: *
225: * @param visitor the visitor who operates on this
226: * <code>MetaProperty</code>
227: *
228: * @return a possible object of interest for the caller.
229: * May be a <code>null</code> value
230: * @throws VisitorException if an internal error occurs while
231: * processing the visited object
232: */
233: public Object accept(MetaProperty.Visitor visitor)
234: throws VisitorException;
235:
236: /**
237: * Obtains the annotations providing additional information for the
238: * MetaProperty represented by this class.
239: * @return the annotations.
240: */
241: public Annotations getAnnotations();
242:
243: /**
244: * Sets the annotations with additional information for the MetaProperty.
245: * Note that this will replace <b>all</b> previous annotations. Use
246: * <code>getAnnotations().set(String, String)</code> if your intention is
247: * to add individual annotations.
248: *
249: * @see Annotations
250: * @param annotations
251: */
252: public void setAnnotations(Annotations annotations);
253: }
|