1 /*
2 Copyright 2007 Ramon Servadei
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 package fulmine.model.field;
17
18 import fulmine.context.IPermissionProfile;
19 import fulmine.model.component.IComponent;
20 import fulmine.model.container.IContainer;
21 import fulmine.protocol.wire.IWireIdentity;
22 import fulmine.protocol.wire.IWireState;
23
24 /**
25 * A field represents a property of an entity. The entity is represented by an
26 * {@link IContainer}. A field can be naturally added to a container and becomes
27 * part of the container's state.
28 * <p>
29 * A field is wire-state aware; it knows its data type and also includes the
30 * logic to read and write its identity and data into byte[] form. <u>The
31 * reading and writing is an asymmetrical operation</u>; a field can write its
32 * identity and data to a byte[] but can only read the data from the byte[], it
33 * cannot read its identity from a byte[], that is the responsibility of the
34 * parent container. This is because a container receives the wire frame and
35 * needs to locate each field expressed in the wire frame and pass the byte[] to
36 * the field.
37 * <p>
38 * A field can have a non-unique wire identity so long as no other field in the
39 * container shares the same wire identity. As an example, a field with a wire
40 * value 'XYZ' can identify a 'foo' field in record type A and a 'bar' field in
41 * record type B. These records are separate objects that will be sent as
42 * separate wire messages and so can share the same field wire value.
43 * <p>
44 * <b>Note</b> fields are equal by their type and encapsulated property value.
45 * Equality does not take into account the record of the field. Thus if 2 fields
46 * both called 'foo', belonging to different records, have the same type and
47 * value, they are equal.
48 * <p>
49 * Fields are given a permission by the creating application code. This
50 * permission governs whether receiving contexts can view the field's value.
51 *
52 * @see IWireState
53 * @see IWireIdentity
54 * @see IPermissionProfile
55 * @author Ramon Servadei
56 */
57 public interface IField extends IComponent, Cloneable
58 {
59
60 /**
61 * Signals the field that it has been added to a container.
62 *
63 * @param container
64 * the container that now has a reference to this
65 */
66 void addedToContainer(IContainer container);
67
68 /**
69 * Get the container this field has been added to
70 *
71 * @return the {@link IContainer} this belongs to
72 */
73 IContainer getContainer();
74
75 /**
76 * Signals the field that it has been removed from a container.
77 *
78 * @param container
79 * the container that removed a reference to this
80 */
81 void removedFromContainer(IContainer container);
82
83 /**
84 * Clone this.
85 *
86 * @see Object#clone
87 * @return a clone of this
88 */
89 Object clone() throws CloneNotSupportedException;
90
91 /**
92 * Get the value of this field as a string.
93 *
94 * @return a string representing the value of this field.
95 */
96 String getValueAsString();
97
98 /**
99 * Get the field value
100 *
101 * @return the field type
102 */
103 Object getValue();
104
105 /**
106 * Get the permission code for the field.
107 *
108 * @see IPermissionProfile
109 *
110 * @return the permission code for the field
111 */
112 short getPermission();
113
114 /**
115 * Get the application code for the field.
116 *
117 * @see IPermissionProfile
118 *
119 * @return the application code for the field
120 */
121 byte getApplication();
122
123 /**
124 * Set the field value from the string. The field converts the string into
125 * the field's data format. If there is an error performing this, the
126 * operation simply returns <code>false</code> or throws a
127 * {@link RuntimeException}.
128 *
129 * @param value
130 * the value to set
131 * @return <code>true</code> if the value changed, <code>false</code> if it
132 * did not or there was a problem converting the string to the
133 * field's data format
134 */
135 boolean setValueFromString(String value);
136 }