A CompoundName is a series of string elements, and it
represents a name in a naming service within a single namespace. Typically
these names have a structure which is hierarchical.
A CompoundName has a sequence of zero or more elements
delimited by the char specified in the property "jndi.syntax.separator". This
property is required except when the direction of the name is "flat" (see
jndi.syntax.direction). The property "jndi.syntax.separator2" allows for the
specification of an additional separator. A separator string will be treated
as normal characters if it is preceded by the escape string or is within
quotes.
The property "jndi.syntax.direction" specifies the direction in which the
name is read. Permitted values are "right_to_left", "left_to_right" and
"flat". A flat name does not have a hierarchical structure. If this property
is not specified then the default is "flat". If this property is specified
with an invalid value then an IllegalArgumentException should
be raised.
Each element can be accessed using its position. The first element is at
position 0. The direction of the name is important. When direction is
"left_to_right" then the leftmost element is at position 0. Conversely when
the direction is "right_to_left" then the rightmost element is at position 0.
There are other properties which affect the syntax of a
CompoundName. The following properties are all optional:
- jndi.syntax.escape - Escape sequence,The escape sequence is used to
escape a quote, separator or escape. When preceded itself by the escape
sequence it is treated as ordinary characters. When it is followed by chars
which are not quote or separator strings then it is treated as ordinary
characters
- jndi.syntax.beginquote - Used as start of quoted string (Defaults to
endquote)
- jndi.syntax.endquote - Used as end of quoted string (Defaults to
beginquote)
- jndi.syntax.beginquote2 - Additionally used as start of quoted string
(Defaults to endquote2)
- jndi.syntax.endquote2 - Additionally used as end of quoted string
(Defaults to beginquote2)
When a non-escaped quote appears at the start of an element it must be
matched at the end. That element can then be said to be quoted. When an
escape sequence appears within a quoted element then it is treated as normal
characters unless it precedes an occurrence of the quote in which case it is
assumed that the quoted element contains a quote which is escaped.
If the element does not start with a quote, then any quote strings within
that element are just normal characters.
- jndi.syntax.ignorecase - If 'true' then ignore case when name elements
are compared. If false or not set then case is important.
- jndi.syntax.trimblanks - If 'true' then ignore leading & trailing blanks
when name elements are compared. If false or not set then blanks are
important.
These 2 properties relate to names where the syntax includes
attribute/content pairs.
- jndi.syntax.separator.ava
- jndi.syntax.separator.typeval
For example the LDAP name, "CN=Mandy Jennings, O=Apache, C=UK". In this
example the pair separator jndi.syntax.separator.ava is ',', and the
character that separates pairs jndi.syntax.separator.typeval is '='. See
RFC1779 for LDAP naming conventions.
The jndi.syntax.separator.ava is not used when manipulating
CompoundName. The jndi.syntax.separator is still used to
separate elements.
The CompoundName needs to be aware of the
jndi.syntax.separator.typeval in case of the instance where a quoted string
is used to provide the content of a pair.
Consider the string "CN=$Mandy Jennings, O=Apache, C=UK" with
- jndi.syntax.direction set to "right_to_left"
- jndi.syntax.separator set to ","
- jndi.syntax.separator.typeval set to "="
When no jndi.syntax.beginquote is set then this creates a valid
CompoundName with 3 elements.
If jndi.syntax.beginquote is then set to "$" the name becomes invalid as the
content part of the pair CN=$Mandy Jennings has a mismatched quote.
The string "CN=$Mandy Jennings$, O=Apache, C=UK" would be fine as the $
quotes round Mandy Jennings now balance.
A CompoundName may be empty. An empty
CompoundName has no elements. Elements may also be empty.
Some Examples:
==============
Consider the following compound name from the file system namespace:
"home/jenningm-abc/.profile"
jndi.syntax.separator is set to '/' as in the UNIX filesystem.
This name has 3 elements:
home jenningm-abc and .profile
The direction should be left_to_right as in the UNIX filesystem
The element at position 0 would be home.
Consider if jndi.syntax.separator had been set to '-' then this name
would have 2 elements:
home/jenningm and abc/.profile
If the direction was right_to_left then the element at position 0
would be abc/.profile.
Consider the name "<ab<cd>ef>" where jndi.syntax.beginquote is <
and jndi.syntax.endquote is >. This will give rise to an
InvalidNameException because a close quote was encountered before
the end of an element. The same is also true for "<abcd>ef>".
If the name was "ab<cd>ef" then this would be valid and there would
be one element ab<cd>ef.
However if the name was "<abcdef>" there would be one element abcdef.
An empty
CompoundName
is the name "" and has no elements.
When jndi.syntax.beginquote is set to " and beginquote2 is set to '
the behaviour is similar to CompositeName -
The name "\"abcd" gives an InvalidNameException as there is no closing quote.
The name "'\"abcd'" gives one element of value "abcd.
The name "\\abcd" gives one element of value \abcd.
Assuming:
jndi.syntax.separator is "/"
jndi.syntax.direction is "left_to_right"
then
"" is empty. It has no elements.
"/" has one empty element.
"//" has 2 empty elements.
"/a/" has 3 elements the middle one is set to a.
"///" has 3 empty elements.
"//a/" has 4 elements, the last but one is set to a.
Assuming the only properties set are:
jndi.syntax.separator is "/"
jndi.syntax.direction is "left_to_right"
then the String
"\"" has one element with the value "
"\\\"" has one element with the value \"
"\\\"'" has one element with the value \"'
Assuming the only properties set are:
jndi.syntax.separator is "/"
jndi.syntax.direction is "left_to_right"
jndi.syntax.beginquote is "\""
then the String
"\"" is invalid because of no closing quote
"\\\"" has one element with the value \"
"\\\"'" has one element with the value \"'
Assuming the only properties set are:
jndi.syntax.separator is "/"
jndi.syntax.direction is "left_to_right"
jndi.syntax.beginquote is "\""
jndi.syntax.beginquote2 is "\'"
then the String
"\"" is invalid because of no closing quote
"\\\"" has one element with the value \"
"\\\"'" has one element with the value \"'
"'\\" is invalid because of no closing quote
| 