1 /*
2 Copyright 2008 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.container;
17
18 import fulmine.IDestroyable;
19 import fulmine.IDomain;
20 import fulmine.IType;
21 import fulmine.Type;
22 import fulmine.context.IFrameworkContext;
23 import fulmine.model.container.impl.Record;
24 import fulmine.model.field.containerdefinition.IContainerDefinitionField;
25
26 /**
27 * Factory held by an {@link IFrameworkContext} to create {@link IContainer}
28 * instances
29 *
30 * @author Ramon Servadei
31 */
32 public interface IContainerFactory extends IDestroyable
33 {
34 /**
35 * A builder for an {@link IContainer}. Implementations are automatically
36 * thread safe if they are invoked from the {@link ContainerFactory}
37 * implementation, which is thread safe.
38 *
39 * @author Ramon Servadei
40 */
41 interface IContainerBuilder
42 {
43 /**
44 * Build an instance of an {@link IContainer}
45 *
46 * @param nativeContextIdentity
47 * whether the container is local
48 * @param identity
49 * the identity of the instance
50 * @param type
51 * the type for the instance
52 * @param domain
53 * the domain for the instance
54 * @param hostContext
55 * the context the instance will be associated with
56 * @param local
57 * <code>true</code> the container is local to this context
58 * @return the created instance
59 */
60 IContainer createContainer(String nativeContextIdentity,
61 String identity, IType type, IDomain domain,
62 IFrameworkContext hostContext, boolean local);
63
64 /**
65 * Get the {@link IContainerDefinitionField} to use for instances of the
66 * container this builder creates. A <code>null</code> definition should
67 * be used for containers that are dynamic.
68 *
69 * @return the {@link IContainerDefinitionField} for instances this
70 * builder creates, <code>null</code> if the container is a
71 * dynamic type.
72 */
73 IContainerDefinitionField createContainerDefinition();
74 }
75
76 /**
77 * Register an {@link IContainerFactory.IContainerBuilder} against the
78 * {@link IContainer} type. This will overwrite any existing builder
79 * registered against the type.
80 *
81 * @param type
82 * the type of the {@link IContainer} the builder creates
83 * @param builder
84 * the container builder to register
85 * @see #containsType(IType)
86 * @see IContainer#getType()
87 * @throws IllegalArgumentException
88 * if the type code ( {@link IType#value()} ) is less than
89 * {@link Type#BASE_USER_START}
90 */
91 void registerBuilder(IType type, IContainerFactory.IContainerBuilder builder);
92
93 /**
94 * Does the factory contain an {@link IContainerFactory.IContainerBuilder}
95 * (and by association, an {@link IContainerDefinitionField}) registered
96 * against the {@link IContainer} type argument.
97 *
98 * @param type
99 * the type of the {@link IContainer} the builder creates
100 * @return <code>true</code> if there is a
101 * {@link IContainerFactory.IContainerBuilder} registered against
102 * the type
103 * @see IContainer#getType()
104 */
105 boolean containsType(IType type);
106
107 /**
108 * Get the {@link IContainerDefinitionField} registered against the
109 * {@link IContainer} type argument. This should not be called for dynamic
110 * container types.
111 *
112 * @param type
113 * the type of the {@link IContainer} the definition applies to
114 * @return the {@link IContainerDefinitionField} for the type of the
115 * {@link IContainer}
116 * @throws IllegalArgumentException
117 * if the {@link IContainer} is a dynamic type (there will be no
118 * {@link IContainerDefinitionField} found)
119 * @see #containsType(IType)
120 * @see IContainer#getType()
121 */
122 IContainerDefinitionField getDefinition(IType type);
123
124 /**
125 * Create an {@link IContainer} implementation from the type argument. If
126 * there is no application {@link IContainerFactory.IContainerBuilder}
127 * registered for the type, a default builder is used that creates an
128 * {@link Record}.
129 *
130 * @param nativeContextIdentity
131 * the name of the context this container is native to - the name
132 * of its local context
133 * @param identity
134 * the identity for the container to create
135 * @param type
136 * the type of the {@link IContainer} implementation to create
137 * @param domain
138 * the domain for the container implementation
139 * @param hostContext
140 * the context hosting this container instance
141 * @param local
142 * <code>true</code> the container is local to this context
143 * @return an {@link IContainer} implementation
144 * @see #containsType(IType)
145 * @see IContainer#getType()
146 */
147 <T extends IContainer> T createContainer(String nativeContextIdentity,
148 String identity, IType type, IDomain domain,
149 IFrameworkContext hostContext, boolean local);
150 }