| Tietue.java |
1 package kanta;
2
3 import java.io.OutputStream;
4 import java.io.PrintStream;
5 import java.io.PrintWriter;
6
7
8 /**
9 * Rajapinta tietueelle johon voidaan taulukon avulla rakentaa
10 * "attribuutit".
11 * @author vesal
12 * @version Mar 23, 2012
13 * @example
14 * <pre name="testJAVA">
15 * public static class Harrastus extends PerusTietue {
16 * private Kentta kentat[] = {
17 * new IntKentta("id"),
18 * new IntKentta("jäsenId"),
19 * new JonoKentta("ala"),
20 * new IntKentta("aloitusvuosi"),
21 * new IntKentta("h/vko")
22 * };
23 * private static int seuraavaNro = 1;
24 * @Override public int ekaKentta() { return 2; }
25 * @Override public Kentta[] getKentat() { return kentat; }
26 * @Override public int getSeuraavaNro() { return seuraavaNro; }
27 * @Override protected void setSeuraavaNro(int i) { seuraavaNro = i; }
28 * @Override protected void setKentat(Kentta[] kentat) { this.kentat = kentat; }
29 * @Override public Harrastus clone() throws CloneNotSupportedException {return (Harrastus)super.clone(); }
30 * public int getJasenNro() { return ((IntKentta)getKentta(1)).getValue(); }
31 * }
32 * </pre>
33 */
34 public interface Tietue {
35
36 /**
37 * @return tietueen kenttien lukumäärä
38 * @example
39 * <pre name="test">
40 * Harrastus har = new Harrastus();
41 * har.getKenttia() === 5;
42 * </pre>
43 */
44 public abstract int getKenttia();
45
46
47 /**
48 * @return ensimmäinen käyttäjän syötettävän kentän indeksi
49 * @example
50 * <pre name="test">
51 * Harrastus har = new Harrastus();
52 * har.ekaKentta() === 2;
53 * </pre>
54 */
55 public abstract int ekaKentta();
56
57
58 /**
59 * @param k Mikä kenttä halutaan
60 * @return k.s kenttä
61 * @example
62 * <pre name="test">
63 * Harrastus har = new Harrastus();
64 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
65 * IntKentta kentta = (IntKentta)har.getKentta(3);
66 * kentta.getValue() === 1949;
67 * </pre>
68 */
69 public abstract Kentta getKentta(int k);
70
71
72 /**
73 * @return palautetaan viite koko kenttätaulukkoon.
74 * @example
75 * <pre name="test">
76 * Harrastus har = new Harrastus();
77 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
78 * Kentta[] kentat = har.getKentat();
79 * ((IntKentta)(kentat[4])).getValue() === 22;
80 * </pre>
81 */
82 public abstract Kentta[] getKentat();
83
84
85 /**
86 * @param k minkä kentän kysymys halutaan
87 * @return valitun kentän kysymysteksti
88 * @example
89 * <pre name="test">
90 * Harrastus har = new Harrastus();
91 * har.getKysymys(2) === "ala";
92 * </pre>
93 */
94 public abstract String getKysymys(int k);
95
96
97 /**
98 * @return kaikkien näytettävien kysymysten otsikot merkkijonotaulukkona
99 * @example
100 * <pre name="test">
101 * #import java.util.Arrays;
102 * Harrastus har = new Harrastus();
103 * Arrays.toString(har.getOtsikot()) =R= "\\[ala, aloitusvuosi, h/vko.*";
104 * </pre>
105 */
106 public abstract String[] getOtsikot();
107
108
109 /**
110 * @param k Minkä kentän sisältö halutaan
111 * @return valitun kentän sisältö
112 * @example
113 * <pre name="test">
114 * Harrastus har = new Harrastus();
115 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
116 * har.anna(0) === "2";
117 * har.anna(1) === "10";
118 * har.anna(2) === "Kalastus";
119 * har.anna(3) === "1949";
120 * har.anna(4) === "22";
121 * </pre>
122 */
123 public abstract String anna(int k);
124
125
126 /**
127 * Kentän sisältö kokonaislukuna. Jos ei ole IntKentta,
128 * niin -1.
129 * @param k Minkä kentän sisältö halutaan
130 * @return valitun kentän sisältö kokonaislukuna.
131 * @example
132 * <pre name="test">
133 * Harrastus har = new Harrastus();
134 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
135 * har.annaInt(0) === 2;
136 * har.annaInt(1) === 10;
137 * har.annaInt(2) === -1;
138 * har.annaInt(3) === 1949;
139 * har.annaInt(4) === 22;
140 * </pre>
141 */
142 public abstract int annaInt(int k);
143
144
145 /**
146 * Asetetaan valitun kentän sisältö. Mikäli asettaminen onnistuu,
147 * palautetaan null, muutoin virheteksti.
148 * @param k minkä kentän sisältö asetetaan
149 * @param s asetettava sisältö merkkijonona
150 * @return null jos ok, muuten virheteksti
151 * @example
152 * <pre name="test">
153 * Harrastus har = new Harrastus();
154 * har.aseta(3,"kissa") === "aloitusvuosi: Ei kokonaisluku (kissa)";
155 * har.aseta(3,"1940") === null;
156 * har.aseta(4,"kissa") === "h/vko: Ei kokonaisluku (kissa)";
157 * har.aseta(4,"20") === null;
158 * </pre>
159 */
160 public abstract String aseta(int k, String s);
161
162
163 /**
164 * Tehdään identtinen klooni tietueesta
165 * @return kloonattu tietue
166 * @throws CloneNotSupportedException jos kloonausta ei tueta
167 * @example
168 * <pre name="test">
169 * #THROWS CloneNotSupportedException
170 * Harrastus har = new Harrastus();
171 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
172 * Harrastus kopio = har.clone();
173 * kopio.toString() === har.toString();
174 * har.parse(" 1 | 11 | Uinti | 1949 | 22 t ");
175 * kopio.toString().equals(har.toString()) === false;
176 * kopio instanceof Harrastus === true;
177 * </pre>
178 */
179 public abstract Tietue clone() throws CloneNotSupportedException;
180
181
182 /**
183 * Tulostetaan tietueen tiedot
184 * @param out tietovirta johon tulostetaan
185 */
186 public abstract void tulosta(PrintWriter out);
187
188
189 /**
190 * Tulostetaan tietueen tiedot
191 * @param os tietovirta johon tulostetaan
192 */
193 public abstract void tulosta(OutputStream os);
194
195
196 /**
197 * Tulostetaan tietueen tiedot
198 * @param out tietovirta johon tulostetaan
199 */
200 public abstract void tulosta(PrintStream out);
201
202
203 /**
204 * Antaa tietueelle seuraavan rekisterinumeron.
205 * @return tietueen uusi tunnus_nro
206 * @example
207 * <pre name="test">
208 * Harrastus pitsi1 = new Harrastus();
209 * pitsi1.getTunnusNro() === 0;
210 * pitsi1.rekisteroi();
211 * int n1 = pitsi1.getTunnusNro();
212 * Harrastus pitsi2 = new Harrastus();
213 * pitsi2.rekisteroi() === n1 + 1;
214 * int n2 = pitsi2.getTunnusNro();
215 * n1 === n2-1;
216 * </pre>
217 */
218 public abstract int rekisteroi();
219
220
221 /**
222 * Palautetaan tietueen oma id
223 * @return tietueen id
224 * @example
225 * <pre name="test">
226 * Harrastus harrastus = new Harrastus();
227 * harrastus.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
228 * harrastus.getTunnusNro() === 2;
229 * </pre>
230 */
231 public abstract int getTunnusNro();
232
233
234 /**
235 * Palauttaa tietueen tiedot merkkijonona jonka voi tallentaa tiedostoon.
236 * @return tietue tolppaeroteltuna merkkijonona
237 * @example
238 * <pre name="test">
239 * Harrastus harrastus = new Harrastus();
240 * harrastus.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
241 * harrastus.toString() =R= "2\\|10\\|Kalastus\\|1949\\|22.*";
242 * </pre>
243 */
244 @Override
245 public abstract String toString();
246
247
248 /**
249 * Selvitää tietueen tiedot | erotellusta merkkijonosta.
250 * Pitää huolen että seuraavaNro on suurempi kuin tuleva tunnusnro.
251 * @param rivi josta tietueen tiedot otetaan
252 * @example
253 * <pre name="test">
254 * Harrastus harrastus = new Harrastus();
255 * harrastus.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
256 * harrastus.getJasenNro() === 10;
257 * harrastus.toString() =R= "2\\|10\\|Kalastus\\|1949\\|22.*";
258 *
259 * harrastus.rekisteroi();
260 * int n = harrastus.getTunnusNro();
261 * harrastus.parse(""+(n+20));
262 * harrastus.rekisteroi();
263 * harrastus.getTunnusNro() === n+20+1;
264 * harrastus.toString() =R= "" + (n+20+1) + "\\|10\\|\\|1949\\|22.*";
265 * </pre>
266 */
267 public abstract void parse(String rivi);
268
269
270 /**
271 * @return seuraava vapaa id-numero
272 * @example
273 * <pre name="test">
274 * Harrastus harrastus = new Harrastus();
275 * harrastus.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
276 * harrastus.rekisteroi();
277 * harrastus.getSeuraavaNro() === harrastus.getTunnusNro()+1;
278 * </pre>
279 */
280 public int getSeuraavaNro();
281
282
283 /**
284 * Antaa k:n kentän sisällön avain-merkkijonona
285 * jonka perusteella voi lajitella
286 * @param k monenenko kentän sisältö palautetaan
287 * @return kentän sisältö merkkijonona
288 * @example
289 * <pre name="test">
290 * Harrastus har = new Harrastus();
291 * har.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
292 * har.getAvain(0) === " 2";
293 * har.getAvain(1) === " 10";
294 * har.getAvain(2) === "KALASTUS";
295 * har.getAvain(20) === "";
296 * </pre>
297 */
298 public abstract String getAvain(int k);
299
300
301 /**
302 * Tutkii onko tietueen tiedot samat kuin parametrina tuodun tietueen tiedot
303 * @param tietue tietue johon verrataan
304 * @return true jos kaikki tiedot samat, false muuten
305 * @example
306 * <pre name="test">
307 * Harrastus har1 = new Harrastus();
308 * har1.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
309 * Harrastus har2 = new Harrastus();
310 * har2.parse(" 2 | 10 | Kalastus | 1949 | 22 t ");
311 * Harrastus har3 = new Harrastus();
312 * har3.parse(" 3 | 12 | Kalastus | 1949 | 22 t ");
313 *
314 *
315 * har1.equals(har2) === true;
316 * har2.equals(har1) === true;
317 * har1.equals(har3) === false;
318 * har3.equals(har2) === false;
319 * </pre>
320 */
321 public abstract boolean equals(Tietue tietue);
322
323 }