Component


1   /***
2   v * Jonathan: an Open Distributed Processing Environment 
3    * Copyright (C) 2001 Kelua SA
4    * 
5    * This library is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2 of the License, or (at your option) any later version.
9    * 
10   * This library is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this library; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   * 
19   * Contact: jonathan@objectweb.org
20   *
21   * Author: Bruno Dumant
22   *
23   * --------------------------------------------------------------------------
24   * $Id: Component.java,v 1.2 2004/01/29 09:54:18 ebruneton Exp $
25   * --------------------------------------------------------------------------
26   * 
27   */
28  
29  package org.objectweb.jonathan.apis.kernel;
30  
31  /** 
32   * The Component interface represents a component, with a value and a type. 
33   */
34  public interface Component {
35     
36     /** 
37      * Returns the element in the target component identified by <code>name</code>, 
38      * null if no element exists under name <code>name</code>.
39      *
40      * @param name the name of the element to be retrieved;
41      * @return the corresponding element, if any; null otherwise.
42      */
43     Element getElement(Name name);   
44  
45     /** 
46      * Returns the component contained in the element registered in the target 
47      * component under the name <code>name</code>.
48      *
49      * A call to <code>getComponent(name)</code> is equivalent to
50      * <code>{@link #getElement(Name) getElement(name)}.{@link Element#getComponent()
51      * getComponent()}</code> if the provided name actually 
52      * corresponds to an element. If it is not the case, null is returned.
53      * 
54      * @param name the name of the element whose component is seeked; 
55      * @return the corresponding component, or null.
56      */
57     Component getComponent(Name name);
58  
59     /** 
60      * Returns the value of the element registered in the target context under 
61      * the name <code>name</code>.
62      *
63      * A call to <code>getValue(name)</code> is equivalent to
64      * <code>{@link #getElement(Name) getElement(name)}.{@link Element#getValue()
65      * getValue()}</code> if the provided name actually 
66      * corresponds to an element. If it is not the case, 
67      * {@link Context#NO_VALUE <code>NO_VALUE</code>} is returned.
68      * 
69      * @param name the name of the element whose value is seeked; 
70      * @return the corresponding value, or {@link Context#NO_VALUE <code>NO_VALUE</code>}.
71      */
72     Object   getValue(Name name);
73  
74     /** 
75      * Returns a distinguished element referencing the target component, if any, 
76      * null otherwise. 
77      * Implementations are not required to keep information about a given containing 
78      * element. It is always legal to return null.
79      * <p>
80      * @return an element containing the target component, if any, null otherwise.
81      */
82     Element getReference();
83  
84     /** 
85      * Sets an element containing the target component. The provided element should
86      * already be initialized as a container of the component. The returned element
87      * is the former container, if any. This method MUST be called when a component
88      * is referred to by an element.
89      *
90      * @param element the new element referencing the target component.
91      * @return the former element referencing the target component, if any, null 
92      *         otherwise.
93      */
94     Element setReference(Element element);
95  
96     /** 
97      * Returns the type of the target component, as a Class.
98      * @return the type of the target component, as a Class.
99      */
100    Class    getType();
101 
102    /** 
103     * Returns the value of the target component, if its type is an object reference
104     * type.
105     * <p>
106     * If the target component is of an integral type, 
107     * {@link Context#NO_VALUE NO_VALUE}} is returned.
108     *
109     * @return the value of the target component.
110     */
111    Object   getValue();
112 
113    /** 
114     * Returns the value of the target component, if its class is an integer class.
115     * <p>
116     * If the target component has an object reference type, Integer.MAX_VALUE is 
117     * returned.
118     *
119     * @return the value of the target component.
120     */
121    int getIntValue();
122 
123    /*
124     * Returns the value of a wrapper of the target component, if the component
125     * has factory alternatives.
126     * @return the value of factory.
127     * @throws JonathanException if the component has not factory alternatives.
128     */
129    Object   getFactoryValue() throws JonathanException;
130 
131 
132    /** 
133     * "Forks" a copy of the target component. The returned component is a
134     * copy of the target component, sharing the same reference, but *NOT*
135     * referred to by this reference. 
136     * <p>
137     * For basic components, this operation simply duplicates the component
138     * structure, but the value is still shared.
139     * <p> 
140     * In the configuration framework, components contain a specification of
141     * their value (in the form of an assemblage, atom, alias... description). 
142     * The fork() method is used to duplicate the specification, but not the
143     * value. It may thus be used to obtain several instances of a component, 
144     * using getValue() on the returned component.
145     * <p> 
146     * When the target component is a context, the returned component is
147     * a new context, roughly containing the forked versions of the target
148     * context's components. 
149     * <p>
150     * If the target context contains an alias, and if the target T of this alias
151     * is in the scope of the context, then the target of the forked alias is a
152     * forked instance of T. But if the target is outside the scope of the
153     * context, then the target of the forked alias is T itself. The context
154     * thus defines a set of components that will be actually duplicated, all
155     * links outside the context being preserved.
156     * <p>
157     * The same rule applies for assemblages, and other "container"
158     * components. For instance, consider an assemblage 'A' made of factory 'F' and
159     * configuration 'C', 'C' containing an atom 'At', an alias 'In' to At, and
160     * an alias 'Out' to a component 'K' outside 'A'. Then the forked version of 'A'
161     * is a new assemblage made of a copy of 'F' and a new configuration
162     * containing a copy 'At2' of 'At', an alias 'In2' to 'At2', and an alias
163     * 'Out2' to 'K'. 
164     * <p>
165     * Aliases are treated specifically. Calling the fork() method on an alias
166     * is like calling the same method on its target.
167     * <p>
168     * @return a forked instance of the target component.
169     */
170    Component fork();
171 
172 }
173
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags