1 /*
2 * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
25
26 package javax.naming;
27
28 import java.util.Enumeration;
29 import java.util.Properties;
30
31 /**
32 * This class represents a composite name -- a sequence of
33 * component names spanning multiple namespaces.
34 * Each component is a string name from the namespace of a
35 * naming system. If the component comes from a hierarchical
36 * namespace, that component can be further parsed into
37 * its atomic parts by using the CompoundName class.
38 *<p>
39 * The components of a composite name are numbered. The indexes of a
40 * composite name with N components range from 0 up to, but not including, N.
41 * This range may be written as [0,N).
42 * The most significant component is at index 0.
43 * An empty composite name has no components.
44 *
45 * <h1>JNDI Composite Name Syntax</h1>
46 * JNDI defines a standard string representation for composite names. This
47 * representation is the concatenation of the components of a composite name
48 * from left to right using the component separator (a forward
49 * slash character (/)) to separate each component.
50 * The JNDI syntax defines the following meta characters:
51 * <ul>
52 * <li>escape (backward slash \),
53 * <li>quote characters (single (') and double quotes (")), and
54 * <li>component separator (forward slash character (/)).
55 * </ul>
56 * Any occurrence of a leading quote, an escape preceding any meta character,
57 * an escape at the end of a component, or a component separator character
58 * in an unquoted component must be preceded by an escape character when
59 * that component is being composed into a composite name string.
60 * Alternatively, to avoid adding escape characters as described,
61 * the entire component can be quoted using matching single quotes
62 * or matching double quotes. A single quote occurring within a double-quoted
63 * component is not considered a meta character (and need not be escaped),
64 * and vice versa.
65 *<p>
66 * When two composite names are compared, the case of the characters
67 * is significant.
68 *<p>
69 * A leading component separator (the composite name string begins with
70 * a separator) denotes a leading empty component (a component consisting
71 * of an empty string).
72 * A trailing component separator (the composite name string ends with
73 * a separator) denotes a trailing empty component.
74 * Adjacent component separators denote an empty component.
75 *
76 *<h1>Composite Name Examples</h1>
77 *This table shows examples of some composite names. Each row shows
78 *the string form of a composite name and its corresponding structural form
79 *({@code CompositeName}).
80 *
81 <table class="striped"><caption style="display:none">examples showing string
82 form of composite name and its corresponding structural form (CompositeName)</caption>
83 <thead>
84 <tr>
85 <th scope="col">String Name</th>
86 <th scope="col">CompositeName</th>
87 </tr>
88 </thead>
89 <tbody style="text-align:left">
90 <tr>
91 <th scope="row">
92 ""
93 </th>
94 <td>{} (the empty name == new CompositeName("") == new CompositeName())
95 </td>
96 </tr>
123 <tr>
124 <th scope="row">"/"</th>
125 <td>{""}</td>
126 </tr>
127
128 <tr>
129 <th scope="row">"//"</th>
130 <td>{"", ""}</td>
131 </tr>
132
133 <tr><th scope="row">"/x/"</th>
134 <td>{"", "x", ""}</td>
135 </tr>
136
137 <tr><th scope="row">"x//y"</th>
138 <td>{"x", "", "y"}</td>
139 </tr>
140 </tbody>
141 </table>
142 *
143 *<h1>Composition Examples</h1>
144 * Here are some composition examples. The right column shows composing
145 * string composite names while the left column shows composing the
146 * corresponding {@code CompositeName}s. Notice that composing the
147 * string forms of two composite names simply involves concatenating
148 * their string forms together.
149
150 <table class="striped"><caption style="display:none">composition examples
151 showing string names and composite names</caption>
152 <thead>
153 <tr>
154 <th scope="col">String Names</th>
155 <th scope="col">CompositeNames</th>
156 </tr>
157 </thead>
158
159 <tbody style="text-align:left">
160 <tr>
161 <th scope="row">
162 "x/y" + "/" = x/y/
163 </th>
178 <tr>
179 <th scope="row">
180 "/" + "x" = "/x"
181 </th>
182 <td>
183 {""} + {"x"} = {"", "x"}
184 </td>
185 </tr>
186
187 <tr>
188 <th scope="row">
189 "x" + "" + "" = "x"
190 </th>
191 <td>
192 {"x"} + {} + {} = {"x"}
193 </td>
194 </tr>
195 </tbody>
196 </table>
197 *
198 *<h1>Multithreaded Access</h1>
199 * A {@code CompositeName} instance is not synchronized against concurrent
200 * multithreaded access. Multiple threads trying to access and modify a
201 * {@code CompositeName} should lock the object.
202 *
203 * @author Rosanna Lee
204 * @author Scott Seligman
205 * @since 1.3
206 */
207
208
209 public class CompositeName implements Name {
210
211 private transient NameImpl impl;
212 /**
213 * Constructs a new composite name instance using the components
214 * specified by 'comps'. This protected method is intended
215 * to be used by subclasses of CompositeName when they override
216 * methods such as clone(), getPrefix(), getSuffix().
217 *
218 * @param comps A non-null enumeration containing the components for the new
|
1 /*
2 * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
25
26 package javax.naming;
27
28 import java.util.Enumeration;
29 import java.util.Properties;
30
31 /**
32 * This class represents a composite name -- a sequence of
33 * component names spanning multiple namespaces.
34 * Each component is a string name from the namespace of a
35 * naming system. If the component comes from a hierarchical
36 * namespace, that component can be further parsed into
37 * its atomic parts by using the CompoundName class.
38 *<p>
39 * The components of a composite name are numbered. The indexes of a
40 * composite name with N components range from 0 up to, but not including, N.
41 * This range may be written as [0,N).
42 * The most significant component is at index 0.
43 * An empty composite name has no components.
44 *
45 * <h2>JNDI Composite Name Syntax</h2>
46 * JNDI defines a standard string representation for composite names. This
47 * representation is the concatenation of the components of a composite name
48 * from left to right using the component separator (a forward
49 * slash character (/)) to separate each component.
50 * The JNDI syntax defines the following meta characters:
51 * <ul>
52 * <li>escape (backward slash \),
53 * <li>quote characters (single (') and double quotes (")), and
54 * <li>component separator (forward slash character (/)).
55 * </ul>
56 * Any occurrence of a leading quote, an escape preceding any meta character,
57 * an escape at the end of a component, or a component separator character
58 * in an unquoted component must be preceded by an escape character when
59 * that component is being composed into a composite name string.
60 * Alternatively, to avoid adding escape characters as described,
61 * the entire component can be quoted using matching single quotes
62 * or matching double quotes. A single quote occurring within a double-quoted
63 * component is not considered a meta character (and need not be escaped),
64 * and vice versa.
65 *<p>
66 * When two composite names are compared, the case of the characters
67 * is significant.
68 *<p>
69 * A leading component separator (the composite name string begins with
70 * a separator) denotes a leading empty component (a component consisting
71 * of an empty string).
72 * A trailing component separator (the composite name string ends with
73 * a separator) denotes a trailing empty component.
74 * Adjacent component separators denote an empty component.
75 *
76 *<h2>Composite Name Examples</h2>
77 *This table shows examples of some composite names. Each row shows
78 *the string form of a composite name and its corresponding structural form
79 *({@code CompositeName}).
80 *
81 <table class="striped"><caption style="display:none">examples showing string
82 form of composite name and its corresponding structural form (CompositeName)</caption>
83 <thead>
84 <tr>
85 <th scope="col">String Name</th>
86 <th scope="col">CompositeName</th>
87 </tr>
88 </thead>
89 <tbody style="text-align:left">
90 <tr>
91 <th scope="row">
92 ""
93 </th>
94 <td>{} (the empty name == new CompositeName("") == new CompositeName())
95 </td>
96 </tr>
123 <tr>
124 <th scope="row">"/"</th>
125 <td>{""}</td>
126 </tr>
127
128 <tr>
129 <th scope="row">"//"</th>
130 <td>{"", ""}</td>
131 </tr>
132
133 <tr><th scope="row">"/x/"</th>
134 <td>{"", "x", ""}</td>
135 </tr>
136
137 <tr><th scope="row">"x//y"</th>
138 <td>{"x", "", "y"}</td>
139 </tr>
140 </tbody>
141 </table>
142 *
143 *<h2>Composition Examples</h2>
144 * Here are some composition examples. The right column shows composing
145 * string composite names while the left column shows composing the
146 * corresponding {@code CompositeName}s. Notice that composing the
147 * string forms of two composite names simply involves concatenating
148 * their string forms together.
149
150 <table class="striped"><caption style="display:none">composition examples
151 showing string names and composite names</caption>
152 <thead>
153 <tr>
154 <th scope="col">String Names</th>
155 <th scope="col">CompositeNames</th>
156 </tr>
157 </thead>
158
159 <tbody style="text-align:left">
160 <tr>
161 <th scope="row">
162 "x/y" + "/" = x/y/
163 </th>
178 <tr>
179 <th scope="row">
180 "/" + "x" = "/x"
181 </th>
182 <td>
183 {""} + {"x"} = {"", "x"}
184 </td>
185 </tr>
186
187 <tr>
188 <th scope="row">
189 "x" + "" + "" = "x"
190 </th>
191 <td>
192 {"x"} + {} + {} = {"x"}
193 </td>
194 </tr>
195 </tbody>
196 </table>
197 *
198 *<h2>Multithreaded Access</h2>
199 * A {@code CompositeName} instance is not synchronized against concurrent
200 * multithreaded access. Multiple threads trying to access and modify a
201 * {@code CompositeName} should lock the object.
202 *
203 * @author Rosanna Lee
204 * @author Scott Seligman
205 * @since 1.3
206 */
207
208
209 public class CompositeName implements Name {
210
211 private transient NameImpl impl;
212 /**
213 * Constructs a new composite name instance using the components
214 * specified by 'comps'. This protected method is intended
215 * to be used by subclasses of CompositeName when they override
216 * methods such as clone(), getPrefix(), getSuffix().
217 *
218 * @param comps A non-null enumeration containing the components for the new
|