1 /*
2 wsmo4j - a WSMO API and Reference Implementation
3
4 Copyright (c) 2004-2005, OntoText Lab. / SIRMA
5
6 This library is free software; you can redistribute it and/or modify it under
7 the terms of the GNU Lesser General Public License as published by the Free
8 Software Foundation; either version 2.1 of the License, or (at your option)
9 any later version.
10 This library is distributed in the hope that it will be useful, but WITHOUT
11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
13 details.
14 You should have received a copy of the GNU Lesser General Public License along
15 with this library; if not, write to the Free Software Foundation, Inc.,
16 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
18
19 /**
20 * <p>Title: WSMO4J</p>
21 * <p>Description: WSMO API and a Reference Implementation</p>
22 * <p>Copyright: Copyright (c) 2004-2005</p>
23 * <p>Company: OntoText Lab. / SIRMA </p>
24 */
25
26 package org.omwg.ontology;
27
28
29 import java.util.*;
30
31 import org.wsmo.common.exception.*;
32
33
34 /**
35 * Defines the requirements for an object that
36 * represents a WSMO relation.
37 *
38 * @see RelationInstance
39 * @author not attributable
40 * @version $Revision: 1946 $ $Date: 2007-04-02 15:13:28 +0300 (Mon, 02 Apr 2007) $
41 */
42 public interface Relation
43 extends OntologyElement {
44
45 /**
46 * Adds a new relation to the set of super-relation of this relation
47 * <i>The super-relation will also add this relation to the list of its sub-relations</i>
48 * @param superRel The new super-relation to be added.
49 * @throws org.wsmo.common.exception.SynchronisationException
50 * @throws org.wsmo.common.exception.InvalidModelException
51 * @see #removeSuperRelation(Relation superRel)
52 */
53 void addSuperRelation(Relation superRel)
54 throws SynchronisationException, InvalidModelException;
55
56 /**
57 * Removes a relation from the set of super-relations of this relation
58 * <i>The super-relation will also remove this relation from the list of its sub-relations</i>
59 * @param superRel The super-relation to be removed
60 * @throws org.wsmo.common.exception.SynchronisationException
61 * @throws org.wsmo.common.exception.InvalidModelException
62 */
63 void removeSuperRelation(Relation superRel)
64 throws SynchronisationException, InvalidModelException;
65
66 /**
67 * Lists the super-relations of this relation
68 * @return The set of super-relation for this relation
69 * @throws org.wsmo.common.exception.SynchronisationException
70 */
71 Set <Relation> listSuperRelations()
72 throws SynchronisationException;
73
74 /**
75 * Adds a new relation to the set of sub-relations of this relation
76 * <i>The sub-relation will also add this relation to the list of its super-relations</i>
77 * @param subRel The new sub-relation to be added.
78 * @throws org.wsmo.common.exception.SynchronisationException
79 * @throws org.wsmo.common.exception.InvalidModelException
80 * @see #removeSubRelation(Relation subRel)
81 */
82 void addSubRelation(Relation subRel)
83 throws SynchronisationException, InvalidModelException;
84
85 /**
86 * Removes a relation from the set of sub-relations of this relation
87 * <i>The sub-relation will also remove this relation from the list of its super-relations</i>
88 * @param subRel The sub-concept to be removed
89 * @throws org.wsmo.common.exception.SynchronisationException
90 * @throws org.wsmo.common.exception.InvalidModelException
91 */
92 void removeSubRelation(Relation subRel)
93 throws SynchronisationException, InvalidModelException;
94
95 /**
96 * Lists the sub-relations of this relation
97 * @return The set of sub-relations defined by this ontology.
98 * @throws org.wsmo.common.exception.SynchronisationException
99 */
100 Set <Relation> listSubRelations()
101 throws SynchronisationException;
102
103 /**
104 * The positioning of the parameters is zero-based, i.e. the first parameter
105 * is at position 0. The initial order of parameters creation must be
106 * succesive, starting from the 0th position. Any other order raises an
107 * InvalidModelException. If this method is called more than once for a
108 * certain position, only the parameter created on the last call is
109 * preserved - all the rest are discarded.
110 * @param pos The position of the new Parameter for this Relation
111 * @throws org.wsmo.common.exception.SynchronisationException
112 * @throws org.wsmo.common.exception.InvalidModelException
113 * @see #removeParameter(Parameter param)
114 * @see #removeParameter(byte pos)
115 * @see #getParameter(byte pos)
116 */
117 Parameter createParameter(byte pos)
118 throws SynchronisationException, InvalidModelException;
119
120 /**
121 * retrieve the parameter at a given position
122 * Note: the parameter must already exist (e.g. a call to createParameter() must precede this call)
123 * @param pos The position of the parameter in interest
124 * @return a reference to the Parameter
125 * @throws org.wsmo.common.exception.SynchronisationException
126 * @see #createParameter(byte pos)
127 */
128 Parameter getParameter(byte pos)
129 throws SynchronisationException;
130
131 /**
132 * The positioning of the parameters is zero-based, i.e. the first parameter
133 * is at position 0. The removal of parameters can only be performed from the
134 * end of the list. Trying to remove a parameter followed by another parameter
135 * will raise an exception.
136 * @param param The parameter to be removed
137 * @throws org.wsmo.common.exception.SynchronisationException
138 * @throws org.wsmo.common.exception.InvalidModelException
139 * @see #removeParameter(byte pos)
140 */
141 void removeParameter(Parameter param)
142 throws SynchronisationException, InvalidModelException;
143
144 /**
145 * Removes a parameter from this relation's list of attributes.
146 * @param pos The position of the parameter to be removed
147 * @throws org.wsmo.common.exception.SynchronisationException
148 * @throws org.wsmo.common.exception.InvalidModelException
149 * @see #removeParameter(Parameter param)
150 */
151 void removeParameter(byte pos)
152 throws SynchronisationException, InvalidModelException;;
153
154 /**
155 * Returns a list of this relation's parameters
156 * @return The list of this relation's parameters
157 * @throws org.wsmo.common.exception.SynchronisationException
158 * @see Parameter
159 */
160 List <Parameter> listParameters()
161 throws SynchronisationException;
162
163 /**
164 * Adds a new RelationInstance to the set of instances of this relation
165 * <i>The relation instance will also set this relation as the relation it is an instance of</i>
166 * @param relInst The new instance to be added.
167 * @throws org.wsmo.common.exception.SynchronisationException
168 * @throws org.wsmo.common.exception.InvalidModelException
169 * @see #removeRelationInstance(RelationInstance relInst)
170 * @see RelationInstance#setRelation(Relation memberOf)
171 */
172 void addRelationInstance(RelationInstance relInst)
173 throws SynchronisationException, InvalidModelException;
174
175 /**
176 * Removes a relation instance from the set of instances of this relation
177 * <i>The relation instance will also set <i>null</i> for as the relation it is an instance of</i>
178 * @param relInst The instance to be removed
179 * @throws org.wsmo.common.exception.SynchronisationException
180 * @throws org.wsmo.common.exception.InvalidModelException
181 * @see RelationInstance#setRelation(Relation memberOf)
182 */
183 void removeRelationInstance(RelationInstance relInst)
184 throws SynchronisationException, InvalidModelException;
185
186 /**
187 * Returns a list of this relation's instances
188 * @return The list of this relation's instances
189 * @throws org.wsmo.common.exception.SynchronisationException
190 * @see RelationInstance
191 */
192 Set <RelationInstance> listRelationInstances()
193 throws SynchronisationException;
194
195 //DO NOT EDIT below this line
196
197 /**
198 * @supplierCardinality 0..*
199 * @directed
200 * @supplierRole super-relation
201 */
202 /*# Relation lnkRelation; */
203
204 /**
205 * @supplierCardinality 0..*
206 * @clientCardinality 1
207 * @supplierRole has-parameter
208 * @clientRole defined-in
209 * @link aggregationByValue
210 */
211 /*# Parameter lnkParameter; */
212
213 /**
214 * @supplierCardinality 0..*
215 * @supplierRole has-instance
216 * @clientCardinality 0..1
217 * @clientRole has-relation
218 */
219 /*# RelationInstance lnkRelationInstance; */
220 }
221
222 /*
223 * $Log$
224 * Revision 1.18 2007/04/02 12:13:14 morcen
225 * Generics support added to wsmo-api, wsmo4j and wsmo-test
226 *
227 * Revision 1.17 2006/01/16 13:31:52 vassil_momtchev
228 * java doc fixed
229 *
230 * Revision 1.16 2005/06/01 10:22:06 marin_dimitrov
231 * v0.4.0
232 *
233 * Revision 1.8 2005/05/13 15:38:26 marin
234 * fixed javadoc errors
235 *
236 * Revision 1.7 2005/05/13 13:58:25 marin
237 * javadoc, header, footer, etc
238 *
239 */