1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package javax.faces.component;
20
21 /**
22 * Interface implemented by components that provide a new "namespace" for the ids of their
23 * child components.
24 * <p>
25 * Component ids must be unique between all descendants of a NamingContainer; the JSF library
26 * will report a fatal error and refuse to process or render any view where two components
27 * in the same NamingContainer have identical id values. However a component that is a descendant
28 * of one NamingContainer component is permitted to have the same id as a component that is a
29 * descendant of a different NamingContainer component.
30 * <p>
31 * Unique component ids are used to:
32 * <ul>
33 * <li>generate unique names for HTML form fields, etc</li>
34 * <li>search for components via UIComponent.findComponent(String expr)</li>
35 * <li>on re-render after postback, match up component declarations in the view templates
36 * with existing components in the restored view tree.
37 * </ul>
38 * <p>
39 * Requiring every component in a large view (which is possibly built by including or
40 * composing multiple files together) to have an id which is different from every other id
41 * is simply unmanageable; JSF certainly must provide <i>some</i> kind of id namespacing.
42 * Therefore this base class is defined, and a few standard JSF components subclass it
43 * (in particular, f:subview).
44 * <p>
45 * When generating clientId values during rendering, descendants of a NamingContainer instance
46 * are allocated a clientId which is their own id prefixed with the clientId of the ancestor
47 * NamingContainer, eg "parentId:childId". NamingContainer components can be nested within
48 * other NamingContainer components, generating clientIds like "firstId:middleId:leafId".
49 * <p>
50 * Not every component is a naming container; that would technically work, but the clientId
51 * values generated would quickly grow excessively long.
52 * <p>
53 * See the javadoc for this class in the
54 * <a href="http://java.sun.com/j2ee/javaserverfaces/1.2/docs/api/index.html">JSF Specification</a>
55 * for further details.
56 *
57 * @author Manfred Geiler (latest modification by $Author: skitching $)
58 * @version $Revision: 685651 $ $Date: 2008-08-13 14:36:16 -0500 (Wed, 13 Aug 2008) $
59 */
60 public interface NamingContainer
61 {
62 public static final char SEPARATOR_CHAR = ':';
63 }