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.containerdefinition;
17
18 import fulmine.context.IPermissionProfile;
19 import fulmine.model.container.IContainer;
20 import fulmine.model.container.impl.Record;
21 import fulmine.model.field.IField;
22 import fulmine.protocol.wire.IWireIdentityRegistry;
23
24 /**
25 * A definition of the {@link IField} objects in an {@link IContainer} object.
26 * Every container has a definition. The definition itself is a field of the
27 * container.
28 * <p>
29 * There are 2 forms of definitions; dynamic and static. Static definitions have
30 * a fixed structure that does not change during runtime (discounting the
31 * initial construction and addition of fields), they are immutable. Dynamic
32 * definitions have a variable structure. This definition distinction arises to
33 * support static and dynamic containers.
34 * <p>
35 * Dynamic containers (e.g. {@link Record}) have a definition per instance, held
36 * in a field. These containers have an indeterminate field population, thus
37 * each dynamic container instance requires its own definition to express the
38 * field population of the container.
39 * <p>
40 * Static container types have a set field population, defined by a static
41 * definition. Thus static containers have a definition per container type not
42 * instance.
43 * <p>
44 * The definition also serves as the wire identity registry for the fields
45 * defined in the container.
46 *
47 * @author Ramon Servadei
48 *
49 */
50 public interface IContainerDefinitionField extends IField,
51 IWireIdentityRegistry, Cloneable
52 {
53 /**
54 * Identify if the definition is dynamic (i.e. mutable)
55 *
56 * @return <code>true</code> if the definition is dynamic
57 */
58 boolean isDynamic();
59
60 /**
61 * Get the IWF wire identity code
62 *
63 * @param wireCode
64 * the integer value of the IWF wire identity
65 * @return the string identity of the associated {@link IField} declared for
66 * this IWF wire identity
67 * @throws IllegalArgumentException
68 * if no field is found
69 */
70 String getIdentityForWireCode(int wireCode);
71
72 /**
73 * Get the IWF wire identity code for the {@link IField} identified by the
74 * string
75 *
76 * @param identity
77 * the string identity of the {@link IField} to find
78 * @return the integer value of the IWF wire identity for the {@link IField}
79 * @throws IllegalArgumentException
80 * if no field is found
81 */
82 int getWireCodeForIdentity(String identity);
83
84 /**
85 * Create the fields in the container from this definition.
86 *
87 * @param container
88 * the container to populate
89 */
90 void populate(IContainer container);
91
92 /**
93 * Add the field to the definition. The field is inspected and a
94 * {@link DescriptorField} is constructed to represent the field. The
95 * descriptor field is held in the definition.
96 *
97 * @param field
98 * the field to represent with a {@link DescriptorField}
99 */
100 void add(IField field);
101
102 /**
103 * Remove the {@link DescriptorField} with the same identity as the field
104 * argument from this definition.
105 *
106 * @param field
107 * the field representation to remove from the definition
108 */
109 void remove(IField field);
110
111 /**
112 * Reset all changes.
113 */
114 void resetChanges();
115
116 /**
117 * Determines if the container definition contains a {@link DescriptorField}
118 * for a field identified by its integer wire identity.
119 *
120 * @param wireCode
121 * the integer wire identity for the field
122 * @return <code>true</code> if there is a {@link DescriptorField} for this
123 * integer wire identity
124 */
125 boolean containsDefinition(int wireCode);
126
127 /**
128 * Create the field identified by its wire code. This only works if there is
129 * a {@link DescriptorField} for the wire identity.
130 *
131 * @see #containsDefinition(int)
132 * @param wireCode
133 * the integer wire identity for the field
134 * @return the created {@link IField} or <code>null</code> if there was no
135 * {@link DescriptorField} for this integer wire identity
136 */
137 IField createField(int wireCode);
138
139 /**
140 * Get the permission code for the field identified by its wire identity
141 *
142 * @see IPermissionProfile
143 *
144 * @param wireCode
145 * the integer wire identity for the field
146 * @return the permission code for the field
147 */
148 short getPermission(int wireCode);
149
150 /**
151 * Get the application code for the field identified by its wire identity
152 *
153 * @see IPermissionProfile
154 *
155 * @param wireCode
156 * the integer wire identity for the field
157 * @return the application code for the field
158 */
159 byte getApplication(int wireCode);
160 }