| Tietueet.java |
1 /**
2 *
3 */
4 package kanta;
5
6 import java.util.Iterator;
7 import java.util.List;
8
9
10
11 /**
12 * Rajapinta rakenteelle, joka tallettaa tietueita.
13 * @author vesal
14 * @version 24.03.2012
15 * @param <TYPE> talletettava tyyppi
16 * @example
17 * <pre name="testJAVA">
18 * public static class Harrastus extends PerusTietue {
19 * private Kentta kentat[] = {
20 * new IntKentta("id"),
21 * new IntKentta("jäsenId"),
22 * new JonoKentta("ala"),
23 * new IntKentta("aloitusvuosi"),
24 * new IntKentta("h/vko")
25 * };
26 * private static int seuraavaNro = 1;
27 * public Harrastus() { }
28 * public Harrastus(int jnro) { ((IntKentta)(kentat[1])).setValue(jnro); }
29 * @Override public int ekaKentta() { return 2; }
30 * @Override public Kentta[] getKentat() { return kentat; }
31 * @Override public int getSeuraavaNro() { return seuraavaNro; }
32 * @Override protected void setSeuraavaNro(int i) { seuraavaNro = i; }
33 * @Override protected void setKentat(Kentta[] kentat) { this.kentat = kentat; }
34 * @Override public Harrastus clone() throws CloneNotSupportedException {return (Harrastus)super.clone(); }
35 * public int getHarrastusNro() { return ((IntKentta)getKentta(1)).getValue(); }
36 * public void vastaaPitsinNyplays(int nro) {
37 * aseta(1,""+nro); aseta(2,"Pitsin nypläys"); aseta(3,"1952"); aseta(4,"30");
38 * }
39 * }
40 * public static class Harrastukset extends PerusTietueet<Harrastus> {
41 * public Harrastukset() { super(new Harrastus(),".har",".hbak"); }
42 * }
43 */
44 public interface Tietueet<TYPE extends Tietue> extends Iterable<TYPE>{
45
46 /**
47 * @return uusi talletettavan tyyppinen alkio
48 */
49 public abstract TYPE luoUusi();
50
51 /**
52 * Lisää uuden harrastuksen tietorakenteeseen. Ottaa harrastuksen omistukseensa.
53 * @param har lisättävä harrastus. Huom tietorakenne muuttuu omistajaksi
54 */
55 public abstract void lisaa(TYPE har);
56
57
58 /**
59 * Korvaa tietueen tietorakenteessa. Ottaa tietueen omistukseensa.
60 * Etsitään samalla tunnusnumerolla oleva tietue. Jos ei löydy,
61 * niin lisätään uutena tietueena.
62 * @param tietue lisätäävän tietueen viite. Huom tietorakenne muuttuu omistajaksi
63 * @throws SailoException jos tietorakennen on jo täynnä
64 * @example
65 * <pre name="test">
66 * #THROWS SailoException,CloneNotSupportedException
67 * #PACKAGEIMPORT
68 * Harrastukset harrastukset = new Harrastukset();
69 * Harrastus har1 = new Harrastus(), har2 = new Harrastus();
70 * har1.rekisteroi(); har2.rekisteroi();
71 * harrastukset.getLkm() === 0;
72 * harrastukset.korvaaTaiLisaa(har1); harrastukset.getLkm() === 1;
73 * harrastukset.korvaaTaiLisaa(har2); harrastukset.getLkm() === 2;
74 * Harrastus har3 = har1.clone();
75 * har3.aseta(2,"kkk");
76 * Iterator<Harrastus> i2=harrastukset.iterator();
77 * i2.next() === har1;
78 * harrastukset.korvaaTaiLisaa(har3); harrastukset.getLkm() === 2;
79 * i2=harrastukset.iterator();
80 * Harrastus h = i2.next();
81 * h === har3;
82 * h == har3 === true;
83 * h == har1 === false;
84 * </pre>
85 */
86 public abstract void korvaaTaiLisaa(TYPE tietue) throws SailoException;
87
88 /**
89 * Poistaa valitun harrastuksen
90 * @param tietue poistettava harrastus
91 * @return tosi jos löytyi poistettava harrastus
92 * @example
93 * <pre name="test">
94 * #THROWS SailoException
95 * #import java.io.File;
96 * Harrastukset harrasteet = new Harrastukset();
97 * Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
98 * Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
99 * Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2);
100 * Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1);
101 * Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2);
102 * harrasteet.lisaa(pitsi21);
103 * harrasteet.lisaa(pitsi11);
104 * harrasteet.lisaa(pitsi22);
105 * harrasteet.lisaa(pitsi12);
106 * harrasteet.poista(pitsi23) === false ; harrasteet.getLkm() === 4;
107 * harrasteet.poista(pitsi11) === true; harrasteet.getLkm() === 3;
108 * List<Harrastus> h = harrasteet.annaTietueet(1,1);
109 * h.size() === 1;
110 * h.get(0) === pitsi12;
111 * </pre>
112 */
113 public abstract boolean poista(TYPE tietue);
114
115
116 /**
117 * Poistaa tietueen jolla on valittu tunnusnumero
118 * @param id poistettavan tietueen tunnusnumero
119 * @return 1 jos poistettiin, 0 jos ei löydy
120 * @example
121 * <pre name="test">
122 * PerusTietueet<Harrastus> harrastukset = new PerusTietueet(new Harrastus());
123 * Harrastus har1 = new Harrastus(), har2 = new Harrastus(), har3 = new Harrastus();
124 * har1.rekisteroi(); har2.rekisteroi(); har3.rekisteroi();
125 * int id1 = har1.getTunnusNro();
126 * harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3);
127 * harrastukset.poista(id1+1) === 1;
128 * harrastukset.poista(id1+1) === 0; harrastukset.getLkm() === 2;
129 * harrastukset.poista(id1) === 1; harrastukset.getLkm() === 1;
130 * harrastukset.poista(id1+3) === 0; harrastukset.getLkm() === 1;
131 * </pre>
132 *
133 */
134 public abstract int poista(int id);
135
136
137 /**
138 * Poistaa kaikki tietyn viittauksen tietueet
139 * @param viiteNro viite siihen, minkä jäsenen harrastukset poistetaan
140 * @param kenttaNro mistä kentästä täytyy vastaava numero löytyä
141 * @return montako poistettiin
142 * @example
143 * <pre name="test">
144 * #THROWS SailoException
145 * #import java.io.File;
146 * Harrastukset harrasteet = new Harrastukset();
147 * Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
148 * Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
149 * Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2);
150 * Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1);
151 * Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2);
152 * harrasteet.lisaa(pitsi21);
153 * harrasteet.lisaa(pitsi11);
154 * harrasteet.lisaa(pitsi22);
155 * harrasteet.lisaa(pitsi12);
156 * harrasteet.lisaa(pitsi23);
157 * harrasteet.poista(2,1) === 3; harrasteet.getLkm() === 2;
158 * harrasteet.poista(3,1) === 0; harrasteet.getLkm() === 2;
159 * List<Harrastus> h = harrasteet.annaTietueet(2,1);
160 * h.size() === 0;
161 * h = harrasteet.annaTietueet(1,1);
162 * h.get(0) === pitsi11;
163 * h.get(1) === pitsi12;
164 * </pre>
165 */
166 public abstract int poista(int viiteNro, int kenttaNro);
167
168
169 /**
170 * Lukee tietueet tiedostosta.
171 * @param tied tiedoston nimen alkuosa
172 * @throws SailoException jos lukeminen epäonnistuu
173 *
174 * @example
175 * <pre name="test">
176 * #THROWS SailoException
177 * #import java.io.File;
178 * Harrastukset harrasteet = new Harrastukset();
179 * Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
180 * Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
181 * Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2);
182 * Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1);
183 * Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2);
184 * String tiedNimi = "testikelmit";
185 * File ftied = new File(tiedNimi+".har");
186 * ftied.delete();
187 * harrasteet.lueTiedostosta(tiedNimi); #THROWS SailoException
188 * harrasteet.lisaa(pitsi21);
189 * harrasteet.lisaa(pitsi11);
190 * harrasteet.lisaa(pitsi22);
191 * harrasteet.lisaa(pitsi12);
192 * harrasteet.lisaa(pitsi23);
193 * harrasteet.talleta();
194 * harrasteet = new Harrastukset();
195 * harrasteet.lueTiedostosta(tiedNimi);
196 * Iterator<Harrastus> i = harrasteet.iterator();
197 * i.next().toString() === pitsi21.toString();
198 * i.next().toString() === pitsi11.toString();
199 * i.next().toString() === pitsi22.toString();
200 * i.next().toString() === pitsi12.toString();
201 * i.next().toString() === pitsi23.toString();
202 * i.hasNext() === false;
203 * harrasteet.lisaa(pitsi23);
204 * harrasteet.talleta();
205 * ftied.delete() === true;
206 * File fbak = new File(tiedNimi+".hbak");
207 * fbak.delete() === true;
208 * </pre>
209 */
210 public abstract void lueTiedostosta(String tied) throws SailoException;
211
212
213 /**
214 * Tallentaa harrastukset tiedostoon.
215 * @throws SailoException jos talletus epäonnistuu
216 */
217 public abstract void talleta() throws SailoException;
218
219
220 /**
221 * Palauttaa kerhon harrastusten lukumäärän
222 * @return harrastusten lukumäärä
223 */
224 public abstract int getLkm();
225
226
227 /**
228 * Asettaa tiedoston perusnimen ilan tarkenninta
229 * @param tied tallennustiedoston perusnimi
230 */
231 public abstract void setTiedostonPerusNimi(String tied);
232
233
234 /**
235 * Palauttaa tiedoston nimen, jota käytetään tallennukseen
236 * @return tallennustiedoston nimi
237 */
238 public abstract String getTiedostonPerusNimi();
239
240
241 /**
242 * Palauttaa tiedoston nimen, jota käytetään tallennukseen
243 * @return tallennustiedoston nimi
244 */
245 public abstract String getTiedostonNimi();
246
247
248 /**
249 * Palauttaa varakopiotiedoston nimen
250 * @return varakopiotiedoston nimi
251 */
252 public abstract String getBakNimi();
253
254
255 /**
256 * Iteraattori kaikkien harrastusten läpikäymiseen
257 * @return harrastusiteraattori
258 *
259 * @example
260 * <pre name="test">
261 * #PACKAGEIMPORT
262 * #import java.util.*;
263 *
264 * Harrastukset harrasteet = new Harrastukset();
265 * Harrastus pitsi21 = new Harrastus(2); harrasteet.lisaa(pitsi21);
266 * Harrastus pitsi11 = new Harrastus(1); harrasteet.lisaa(pitsi11);
267 * Harrastus pitsi22 = new Harrastus(2); harrasteet.lisaa(pitsi22);
268 * Harrastus pitsi12 = new Harrastus(1); harrasteet.lisaa(pitsi12);
269 * Harrastus pitsi23 = new Harrastus(2); harrasteet.lisaa(pitsi23);
270 *
271 * Iterator<Harrastus> i2=harrasteet.iterator();
272 * i2.next() === pitsi21;
273 * i2.next() === pitsi11;
274 * i2.next() === pitsi22;
275 * i2.next() === pitsi12;
276 * i2.next() === pitsi23;
277 * i2.next() === pitsi12; #THROWS NoSuchElementException
278 *
279 * int n = 0;
280 * int jnrot[] = {2,1,2,1,2};
281 *
282 * for ( Harrastus har:harrasteet ) {
283 * har.getHarrastusNro() === jnrot[n]; n++;
284 * }
285 *
286 * n === 5;
287 *
288 * </pre>
289 */
290 @Override
291 public abstract Iterator<TYPE> iterator();
292
293
294 /**
295 * Laitetaan muutos, jolloin pakotetaan tallentamaan.
296 */
297 public abstract void setMuutos();
298
299
300 /**
301 * Haetaan kaikki tietyn viitteen tietueet
302 * @param tunnusnro etsittävän viitteen tunnusnumero jolle tietueita haetaan
303 * @param k etsittävän kentän numero
304 * @return tietorakenne jossa viiteet löydetteyihin tietueisiin
305 * @example
306 * <pre name="test">
307 * #import java.util.*;
308 *
309 * Harrastukset harrasteet = new Harrastukset();
310 * Harrastus pitsi21 = new Harrastus(2); harrasteet.lisaa(pitsi21);
311 * Harrastus pitsi11 = new Harrastus(1); harrasteet.lisaa(pitsi11);
312 * Harrastus pitsi22 = new Harrastus(2); harrasteet.lisaa(pitsi22);
313 * Harrastus pitsi12 = new Harrastus(1); harrasteet.lisaa(pitsi12);
314 * Harrastus pitsi23 = new Harrastus(2); harrasteet.lisaa(pitsi23);
315 * Harrastus pitsi51 = new Harrastus(5); harrasteet.lisaa(pitsi51);
316 *
317 * List<Harrastus> loytyneet;
318 * loytyneet = harrasteet.annaTietueet(3,1);
319 * loytyneet.size() === 0;
320 * loytyneet = harrasteet.annaTietueet(1,1);
321 * loytyneet.size() === 2;
322 * loytyneet.get(0) == pitsi11 === true;
323 * loytyneet.get(1) == pitsi12 === true;
324 * loytyneet = harrasteet.annaTietueet(5,1);
325 * loytyneet.size() === 1;
326 * loytyneet.get(0) == pitsi51 === true;
327 * </pre>
328 */
329 public abstract List<TYPE> annaTietueet(int tunnusnro, int k);
330
331
332 /**
333 * Palauttaa "taulukossa" hakuehtoon vastaavien tietueiden viitteet
334 * @param hakuehto hakuehto
335 * @param k etsittävän kentän indeksi
336 * @return tietorakenteen löytyneistä tietueista
337 * @example
338 * <pre name="test">
339 * #THROWS SailoException
340 * Harrastukset harrastukset = new Harrastukset();
341 * Harrastus har1 = new Harrastus(); har1.parse("1|2|Possujen jahtaaminen|1940|22");
342 * Harrastus har2 = new Harrastus(); har2.parse("2|1|Poikien hoitaminen|1953|1");
343 * Harrastus har3 = new Harrastus(); har3.parse("3|2|Kelmien kerho|1948|20");
344 * Harrastus har4 = new Harrastus(); har4.parse("4|1|Kalastus|1947|20");
345 * Harrastus har5 = new Harrastus(); har5.parse("5|3|Viulu|1952|15");
346 * harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3);
347 * harrastukset.lisaa(har4); harrastukset.lisaa(har5);
348 * List<Harrastus> loytyneet;
349 * loytyneet = harrastukset.etsi("*s*",2);
350 * loytyneet.size() === 2;
351 * loytyneet.get(0) == har4 === true;
352 * loytyneet.get(1) == har1 === true;
353 *
354 * loytyneet = harrastukset.etsi("*5*",3);
355 * loytyneet.size() === 2;
356 * loytyneet.get(0) == har5 === true;
357 * loytyneet.get(1) == har2 === true;
358 * </pre>
359 */
360 public abstract List<TYPE> etsi(String hakuehto, int k);
361
362
363 /**
364 * Etsii tietueen id:n perusteella
365 * @param id tunnusnumero, jonka mukaan etsitään
366 * @return tietue jolla etsittävä id tai null
367 * @example
368 * <pre name="test">
369 * Harrastukset harrastukset = new Harrastukset();
370 * Harrastus har1 = new Harrastus(); har1.parse("1|2|Possujen jahtaaminen|1940|22");
371 * Harrastus har2 = new Harrastus(); har2.parse("2|1|Poikien hoitaminen|1953|1");
372 * Harrastus har3 = new Harrastus(); har3.parse("3|2|Kelmien kerho|1948|20");
373 * harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3);
374 * harrastukset.annaId(1) == har1 === true;
375 * harrastukset.annaId(2) == har2 === true;
376 * harrastukset.annaId(3) == har3 === true;
377 * </pre>
378 */
379 public abstract TYPE annaId(int id);
380 }