01: /* IdSpace.java
02:
03: {{IS_NOTE
04: Purpose:
05:
06: Description:
07:
08: History:
09: Fri Jul 29 10:41:31 2005, Created by tomyeh
10: }}IS_NOTE
11:
12: Copyright (C) 2005 Potix Corporation. All Rights Reserved.
13:
14: {{IS_RIGHT
15: This program is distributed under GPL Version 2.0 in the hope that
16: it will be useful, but WITHOUT ANY WARRANTY.
17: }}IS_RIGHT
18: */
19: package org.zkoss.zk.ui;
20:
21: /**
22: * Implemented by a component ({@link Component}) and a page
23: * ({@link Page})
24: * to denote that all its descendant and itself forms an independent ID space.
25: *
26: * <p>In an ID space, ID of each component ({@link Component#getId}) must be
27: * unique.
28: * And, you could retrieve any component in the same ID space by calling
29: * {@link #getFellow} upon any component of the same ID space.
30: *
31: * <p>For sake of description, components in the same ID space are called
32: * fellows.
33: * If the component has an ancestor which implements {@link IdSpace},
34: * we say a component belongs to the ID space owned by the ancestor.
35: * If no such ancestor exists, the component belongs to the ID space
36: * owned by the page.
37: * The ancestor and the page is called the owner
38: * ({@link Component#getSpaceOwner}).
39: *
40: * <p>For sake of description, we also call the ID space as space X, if
41: * the owner is component X (or page X).
42: * If component Y is a child of X and also implements {@link IdSpace}
43: * (aka., another owner), then space X includes component Y, but
44: * EXCLUDES descendants of Y. In other words, Y belongs to space X and space Y.
45: * Thus, to get a child Z in the Y space, you shall X.getFellow('Y').getFellow('Z').
46: *
47: * <p>Example: Assumes component A is a child of B, B a child of C and
48: * C a child of D. If only C implements {@link IdSpace}, A, B and C are all
49: * belonged to the C space. D doesn't belong any space.
50: *
51: * <p>If both C and D implements {@link IdSpace}, C and D belongs
52: * to the D space while A, B and C belongs to the C space.
53: *
54: * <p>Note: to make a component (deriving from {@link AbstractComponent})
55: * an ID space owner, all it needs to do is to implement this interface.
56: *
57: * @author tomyeh
58: */
59: public interface IdSpace {
60: /** Returns a component of the specified ID in the same ID space.
61: * Components in the same ID space are called fellows.
62: *
63: * <p>Unlike {@link #getFellowIfAny}, it throws an exception if not found.
64: *
65: * @exception ComponentNotFoundException is thrown if
66: * this component doesn't belong to any ID space
67: */
68: public Component getFellow(String id);
69:
70: /** Returns a component of the specified ID in the same ID space, or null
71: * if not found.
72: * <p>Unlike {@link #getFellow}, it returns null if not found.
73: */
74: public Component getFellowIfAny(String id);
75: }
|