Fix: default FN should be trimmed
[jvcard.git] / src / be / nikiroo / jvcard / BaseClass.java
... / ...
CommitLineData
1package be.nikiroo.jvcard;
2
3import java.security.InvalidParameterException;
4import java.util.ArrayList;
5import java.util.Collection;
6import java.util.Collections;
7import java.util.Comparator;
8import java.util.Iterator;
9import java.util.LinkedList;
10import java.util.List;
11import java.util.ListIterator;
12
13import be.nikiroo.jvcard.resources.StringUtils;
14
15/**
16 * This class is basically a List with a parent and a "dirty" state check. It
17 * sends all commands down to the initial list, but will mark itself and its
18 * children as dirty or not when needed.
19 *
20 * <p>
21 * All child elements can identify their parent, and must not be added to 2
22 * different objects without without first being removed from the previous one.
23 * </p>
24 *
25 * <p>
26 * The dirty state is bubbling up (when dirty = true) or down (when dirty =
27 * false) -- so, making changes to a child element will also mark its parent as
28 * "dirty", and marking an element as pristine will also affect all its child
29 * elements.
30 * </p>
31 *
32 * @author niki
33 *
34 * @param <E>
35 * the type of the child elements
36 */
37public abstract class BaseClass<E extends BaseClass<?>> implements List<E> {
38 protected boolean dirty;
39 protected BaseClass<?> parent;
40 private List<E> list;
41
42 private Comparator<E> comparator = new Comparator<E>() {
43 @Override
44 public int compare(E o1, E o2) {
45 if (o1 == null && o2 == null)
46 return 0;
47 if (o1 == null && o2 != null)
48 return -1;
49 if (o1 != null && o2 == null)
50 return 1;
51
52 return o1.getId().compareTo(o2.getId());
53 }
54 };
55
56 /**
57 * Create a new {@link BaseClass} with the items in the given list as its
58 * descendants.
59 *
60 * Note: the elements will be copied from the {@link List}, you cannot
61 * manage the {@link List} from outside
62 *
63 * @param list
64 * the descendants of this object, or NULL if none
65 */
66 protected BaseClass(List<E> list) {
67 this.list = new ArrayList<E>();
68
69 if (list != null) {
70 this.list.addAll(list);
71 }
72
73 for (E child : this) {
74 _enter(child, true);
75 }
76 }
77
78 /**
79 * Check if this element has unsaved changes.
80 *
81 * @return TRUE if it has
82 */
83 public boolean isDirty() {
84 return dirty;
85 }
86
87 /**
88 * Delete this element from its parent if any.
89 *
90 * @return TRUE in case of success
91 */
92 public boolean delete() {
93 if (parent != null) {
94 return parent.remove(this);
95 }
96
97 return false;
98 }
99
100 /**
101 * Replace the elements contained in this with those in the given
102 * {@link List}.
103 *
104 * Note: the elements will be copied from the {@link List}, you cannot
105 * manage the {@link List} from outside
106 *
107 * @param list
108 * the list of new elements
109 */
110 public void replaceListContent(List<E> list) {
111 List<E> del = new LinkedList<E>();
112 List<E> add = new LinkedList<E>();
113
114 if (!compare(list, add, del, del, add)) {
115 removeAll(del);
116 addAll(add);
117 }
118 }
119
120 /**
121 * Compare the elements contained in <tt>this</tt> with those in the given
122 * {@link List}. It will return TRUE in case of equality, will return FALSE
123 * if not.
124 *
125 * If not equals, the differences will be represented by the given
126 * {@link List}s if they are not NULL.
127 * <ul>
128 * <li><tt>added</tt> will represent the elements in <tt>list</tt> but not
129 * in <tt>this</tt></li>
130 * <li><tt>removed</tt> will represent the elements in <tt>this</tt> but not
131 * in <tt>list</tt></li>
132 * <li><tt>from<tt> will represent the elements in <tt>list</tt> that are
133 * already contained in <tt>this</tt> but are not equals to them (the
134 * original element from <tt>this</tt> is stored here)</li>
135 * <li><tt>to<tt> will represent the elements in <tt>list</tt> that are
136 * already contained in <tt>this</tt> but are not equals to them (the
137 * changed element from <tt>list</tt> is stored here)</li>
138 * </ul>
139 *
140 * @param list
141 * the list of new elements
142 * @param added
143 * the list to add the <tt>added</tt> elements to, or NULL
144 * @param removed
145 * the list to add the <tt>removed</tt> elements to, or NULL
146 * @param from
147 * the map to add the <tt>from</tt> elements, or NULL
148 * @param to
149 * the map to add the <tt>to</tt> elements, or NULL
150 *
151 * @return TRUE if the elements are identical
152 */
153 @SuppressWarnings({ "unchecked", "rawtypes" })
154 public boolean compare(List<E> list, List<E> added, List<E> removed,
155 List<E> from, List<E> to) {
156 Collections.sort(this.list, comparator);
157
158 List<E> mine = new LinkedList<E>(this.list);
159 List<E> other = new LinkedList<E>(list);
160
161 Collections.sort(other, comparator);
162
163 boolean equ = true;
164 E here = mine.size() > 0 ? mine.remove(0) : null;
165 E there = other.size() > 0 ? other.remove(0) : null;
166
167 while (here != null || there != null) {
168 if (here == null
169 || (there != null && comparator.compare(here, there) > 0)) {
170 if (added != null)
171 added.add(there);
172 there = null;
173 equ = false;
174 } else if (there == null || comparator.compare(here, there) < 0) {
175 if (removed != null)
176 removed.add(here);
177 here = null;
178 equ = false;
179 } else {
180 // they represent the same item
181 if (!((BaseClass) here).isEquals(there, false)) {
182 if (from != null)
183 from.add(here);
184 if (to != null)
185 to.add(there);
186 equ = false;
187 }
188 here = null;
189 there = null;
190 }
191
192 if (here == null && mine.size() > 0)
193 here = mine.remove(0);
194 if (there == null && other.size() > 0)
195 there = other.remove(0);
196 }
197
198 return equ;
199 }
200
201 /**
202 * Check if the given instance and this one represent the same objects (they
203 * may have different states).
204 *
205 * @param other
206 * the other instance
207 *
208 * @return TRUE if they represent the same object
209 */
210 public boolean isSame(BaseClass<E> other) {
211 if (other == null)
212 return false;
213
214 if (!getClass().equals(other.getClass()))
215 return false;
216
217 return getId().equals(other.getId());
218 }
219
220 /**
221 * Check if the given instance and this one are equivalent (both objects in
222 * the same state, all child elements equivalent).
223 *
224 * @param other
225 * the other instance
226 *
227 * @param contentOnly
228 * do not check the state of the object itslef, only its content
229 *
230 * @return TRUE if they are equivalent
231 */
232 @SuppressWarnings({ "unchecked", "rawtypes" })
233 public boolean isEquals(BaseClass<E> other, boolean contentOnly) {
234 if (other == null)
235 return false;
236
237 if (size() != other.size())
238 return false;
239
240 if (!contentOnly) {
241 if (!isSame(other))
242 return false;
243
244 if (!getState().equals(other.getState()))
245 return false;
246 }
247
248 Collections.sort(list, comparator);
249 Collections.sort(other.list, other.comparator);
250 for (int index = 0; index < size(); index++) {
251 if (!((BaseClass) get(index)).isEquals(other.get(index), false))
252 return false;
253 }
254
255 return true;
256 }
257
258 /**
259 * Get the recursive state of the current object, i.e., its children
260 * included. It represents the full state information about this object's
261 * children. It may not contains spaces nor new lines.
262 *
263 * <p>
264 * Not that this state is <b>lossy</b>. You cannot retrieve the data from
265 * the state, it can only be used as an ID to check if data are identical.
266 * </p>
267 *
268 * @param self
269 * also include state information about the current object itself
270 * (as opposed to its children)
271 *
272 * @return a {@link String} representing the current content state of this
273 * object, i.e., its children included
274 */
275 public String getContentState(boolean self) {
276 StringBuilder builder = new StringBuilder();
277 buildContentStateRaw(builder, self);
278 return StringUtils.getHash(builder.toString());
279 }
280
281 /**
282 * Return the (first) child element with the given ID or NULL if not found.
283 *
284 * @param id
285 * the id to look for
286 *
287 * @return the child element or NULL
288 */
289 public E getById(String id) {
290 for (E child : this) {
291 if (id == null) {
292 if (child.getId() == null)
293 return child;
294 } else {
295 if (id.equals(child.getId()))
296 return child;
297 }
298 }
299
300 return null;
301 }
302
303 /**
304 * Return a {@link String} that can be used to identify this object in DEBUG
305 * mode, i.e., a "toString" method that can identify the object's content
306 * but still be readable in a log.
307 *
308 * @param depth
309 * the depth into which to descend (0 = only this object, not its
310 * children)
311 *
312 * @return the debug {@link String}
313 */
314 public String getDebugInfo(int depth) {
315 StringBuilder builder = new StringBuilder();
316 getDebugInfo(builder, depth, 0);
317 return builder.toString();
318 }
319
320 /**
321 * Return the current ID of this object -- it is allowed to change over time
322 * (so, do not cache it).
323 *
324 * @return the current ID
325 */
326 abstract public String getId();
327
328 /**
329 * Get the state of the current object, children <b>not included</b>. It
330 * represents the full state information about this object, but do not check
331 * its children (see {@link BaseClass#getContentState()} for that). It may
332 * not contains spaces nor new lines.
333 *
334 * <p>
335 * Not that this state is <b>lossy</b>. You cannot retrieve the data from
336 * the state, it can only be used as an ID to check if thw data are
337 * identical.
338 * </p>
339 *
340 * @return a {@link String} representing the current state of this object,
341 * children not included
342 */
343 abstract public String getState();
344
345 /**
346 * Get the recursive state of the current object, i.e., its children
347 * included. It represents the full state information about this object's
348 * children.
349 *
350 * It is not hashed.
351 *
352 * @param builder
353 * the {@link StringBuilder} that will represent the current
354 * content state of this object, i.e., its children included
355 * @param self
356 * also include state information about the current object itself
357 * (as opposed to its children)
358 */
359 void buildContentStateRaw(StringBuilder builder, boolean self) {
360 Collections.sort(this.list, comparator);
361 if (self)
362 builder.append(getState());
363 for (E child : this) {
364 child.buildContentStateRaw(builder, true);
365 }
366 }
367
368 /**
369 * Populate a {@link StringBuilder} that can be used to identify this object
370 * in DEBUG mode, i.e., a "toString" method that can identify the object's
371 * content but still be readable in a log.
372 *
373 * @param depth
374 * the depth into which to descend (0 = only this object, not its
375 * children)
376 *
377 * @param tab
378 * the current tabulation increment
379 */
380 void getDebugInfo(StringBuilder builder, int depth, int tab) {
381 for (int i = 0; i < tab; i++)
382 builder.append(" ");
383 builder.append(getContentState(false) + " " + getId());
384
385 if (depth > 0)
386 builder.append(": [");
387
388 if (depth > 0) {
389 for (E child : this) {
390 builder.append("\n");
391 child.getDebugInfo(builder, depth - 1, tab + 1);
392 }
393 }
394 if (depth > 0) {
395 builder.append("\n");
396 for (int i = 0; i < tab; i++)
397 builder.append(" ");
398 builder.append("]");
399 }
400 }
401
402 /**
403 * Notify that this element has unsaved changes.
404 */
405 void setDirty() {
406 dirty = true;
407 if (parent != null) {
408 parent.setDirty();
409 }
410 }
411
412 /**
413 * Notify this element <i>and all its descendants</i> that it is in pristine
414 * state (as opposed to dirty).
415 */
416 void setPristine() {
417 dirty = false;
418 for (E child : this) {
419 child.setPristine();
420 }
421 }
422
423 /**
424 * Set the parent of this element <i>and all its descendants</i>.
425 *
426 * @param parent
427 * the new parent
428 */
429 void setParent(BaseClass<?> parent) {
430 this.parent = parent;
431 for (E child : this) {
432 child.setParent(this);
433 }
434 }
435
436 /**
437 * Escape the given value to VCF standard.
438 *
439 * @param value
440 * the value to escape
441 *
442 * @return the escaped value
443 */
444 protected String escape(String value) {
445 if (value == null)
446 return null;
447
448 return value.replaceAll(",", "\\\\,").replaceAll(";", "\\\\;")
449 .replaceAll("\n", "\\\\n");
450 }
451
452 /**
453 * Unescape the given value from the VCF standard.
454 *
455 * @param value
456 * the value to unescape
457 *
458 * @return the unescaped value
459 */
460 protected String unescape(String value) {
461 if (value == null)
462 return null;
463
464 return value.replaceAll("\\\\,", ",").replaceAll("\\\\;", ";")
465 .replaceAll("\\\\n", "\n");
466 }
467
468 /**
469 * Each element that leaves the parent will pass trough here.
470 *
471 * @param child
472 * the element to remove from this
473 */
474 private void _leave(E child) {
475 if (child.parent != null && child.parent != this) {
476 throw new InvalidParameterException(
477 "You are removing this child from its rightful parent, it must be yours to do so");
478 }
479
480 child.parent = null;
481 setDirty();
482 }
483
484 /**
485 * Each element that enters the parent will pass trough here.
486 *
487 * @param child
488 * the element to add to this
489 */
490 private void _enter(E child) {
491 _enter(child, false);
492 }
493
494 /**
495 * Each element that enters the parent will pass trough here.
496 *
497 * @param child
498 * the element to add to this
499 */
500 private void _enter(E child, boolean initialLoad) {
501 if (child.parent != null && child.parent != this) {
502 throw new InvalidParameterException(
503 "You are stealing this child from its rightful parent, you must remove it first");
504 }
505
506 child.setParent(this);
507 if (!initialLoad) {
508 setDirty();
509 child.setDirty();
510 }
511 }
512
513 @Override
514 public boolean add(E e) {
515 _enter(e, false);
516 return list.add(e);
517 }
518
519 @Override
520 @SuppressWarnings("unchecked")
521 public boolean remove(Object o) {
522 if (list.remove(o)) {
523 if (o instanceof BaseClass<?>) {
524 _leave((E) o); // expected warning
525 }
526 return true;
527 }
528
529 return false;
530 }
531
532 @Override
533 public boolean addAll(Collection<? extends E> c) {
534 for (E child : c) {
535 _enter(child);
536 }
537
538 return list.addAll(c);
539 }
540
541 @Override
542 public boolean addAll(int index, Collection<? extends E> c) {
543 for (E child : c) {
544 _enter(child);
545 }
546
547 return list.addAll(index, c);
548 }
549
550 @Override
551 public boolean removeAll(Collection<?> c) {
552 boolean changed = false;
553
554 for (Object o : c) {
555 if (remove(o))
556 changed = true;
557 }
558
559 return changed;
560 }
561
562 @Override
563 public boolean retainAll(Collection<?> c) {
564 ArrayList<Object> del = new ArrayList<Object>();
565 for (Object o : c) {
566 del.add(o);
567 }
568 return removeAll(del);
569 }
570
571 @Override
572 public void clear() {
573 for (E child : this) {
574 _leave(child);
575 }
576
577 list.clear();
578 }
579
580 @Override
581 public E set(int index, E element) {
582 E child = get(index);
583 if (child != null)
584 _leave(child);
585 _enter(element);
586
587 return list.set(index, element);
588 }
589
590 @Override
591 public void add(int index, E element) {
592 _enter(element);
593 list.add(index, element);
594 }
595
596 @Override
597 public E remove(int index) {
598 E child = get(index);
599 _leave(child);
600 return list.remove(index);
601 }
602
603 @Override
604 public Iterator<E> iterator() {
605 return listIterator(0);
606 }
607
608 @Override
609 public ListIterator<E> listIterator() {
610 return listIterator(0);
611 }
612
613 @Override
614 public ListIterator<E> listIterator(int index) {
615 final int i = index;
616 return new ListIterator<E>() {
617 ListIterator<E> base = list.listIterator(i);
618 E last;
619
620 @Override
621 public boolean hasNext() {
622 return base.hasNext();
623 }
624
625 @Override
626 public E next() {
627 last = base.next();
628 return last;
629 }
630
631 @Override
632 public boolean hasPrevious() {
633 return base.hasPrevious();
634 }
635
636 @Override
637 public E previous() {
638 last = base.previous();
639 return last;
640 }
641
642 @Override
643 public int nextIndex() {
644 return base.nextIndex();
645 }
646
647 @Override
648 public int previousIndex() {
649 return base.previousIndex();
650 }
651
652 @Override
653 public void remove() {
654 base.remove();
655 _leave(last);
656 }
657
658 @Override
659 public void set(E e) {
660 base.set(e);
661 _leave(last);
662 _enter(e);
663 }
664
665 @Override
666 public void add(E e) {
667 base.add(e);
668 _enter(e);
669 }
670 };
671 }
672
673 @Override
674 public Object[] toArray() {
675 return list.toArray();
676 }
677
678 @Override
679 public <T> T[] toArray(T[] a) {
680 return list.toArray(a);
681 }
682
683 @Override
684 public int size() {
685 return list.size();
686 }
687
688 @Override
689 public boolean isEmpty() {
690 return list.isEmpty();
691 }
692
693 @Override
694 public boolean contains(Object o) {
695 return list.contains(o);
696 }
697
698 @Override
699 public boolean containsAll(Collection<?> c) {
700 return list.containsAll(c);
701 }
702
703 @Override
704 public E get(int index) {
705 return list.get(index);
706 }
707
708 @Override
709 public int indexOf(Object o) {
710 return list.indexOf(o);
711 }
712
713 @Override
714 public int lastIndexOf(Object o) {
715 return list.lastIndexOf(o);
716 }
717
718 @Override
719 public List<E> subList(int fromIndex, int toIndex) {
720 return list.subList(fromIndex, toIndex);
721 }
722}