Top Description Fields Constructors Methods
org.apache.derby.iapi.util

public abstract Class IdUtil

extends Object
Class Inheritance
Imports
org.apache.derby.shared.common.reference.Attribute, .SQLState, .Property, .Limits, org.apache.derby.shared.common.error.StandardException, java.io.IOException, .StringReader, java.util.Vector, .HashSet, .Properties
Utility class for parsing and producing string representations of ids. This class supports both delimited and un-delimited ids.

The syntax for an id follows. 

      id := delim-id | unDelim-id

	  delim-id := "[""|[any char but quote]]+"
	  undelim-id := (a-z|A-Z|anyunicodeletter)[a-z|A-Z|_|0-9|anyunicodeletter|anyunicodedigit]*

	  In the syntax braces show grouping. '*' means repeat 0 or more times.
	  '|' means or. '+' means repeat 1 or more times.

In addition this class provides support for qualified names. A qualified name is a dot (.) separated list of ids.

Limitations:

  1. Unicode escape sequences in ids are not supported.
  2. Escape sequences (\n...) are not supported.

Field Summary

Modifier and TypeField and Description
public static final int
DBCP_SCHEMA_NAME

Index of the schema name in a jar name on a db classpath

public static final int
DBCP_SQL_JAR_NAME

Index of the sql jar name in a jar name on a db classpath

Constructor Summary

AccessConstructor and Description
public
IdUtil()

Method Summary

Modifier and TypeMethod and Description
public static String

Returns:

the list with the id appended in its delimited form.
appendNormalToList(String id, String list)

Append an identifier to a comma separated list of identifiers.

public static void
checkIdentifierLengthLimit(String
identifier (in case normal form) to check
identifier, int
maximum legal length
identifier_length_limit)

Check that identifier is not too long

public static String

Returns:

the list with the id deleted or null if the resulting list has no ids. If 'id' is not on 'list' this returns list unchanged. If list becomes empty after the removal null is returned.
deleteId(String
an id in normal form (quotes removed, upshifted if regular)
id, String
a comma separated list of ids in external form (possibly delmited or not upshifted).
list)

Delete an normal value from a list of SQL identifiers.

public static String
dups(String[]
a list of ids in normal form.
l)

Return an IdList with all the ids that are repeated in l.

public static String
getUserAuthorizationId(String userName)

Map userName to authorizationId in its normal form.

public static String
getUserNameFromURLProps(Properties params)

Get user name from URL properties (key user) without any transformation.

private static boolean
idChar(boolean first, int c)

public static boolean
idOnList(String
an id in normal form
id, String
a list of ids in external form.
list)

Return true if the normalized value of an indentifier is on the list of SQL identifiers provided.

public static String
intersect(String[]
An array of ids in normal form
l1, String[]
An array of ids in nomral form
l2)

Return an IdList with all the ids that in l1 and l2 or null if not ids are on both lists.

public static String
mkIdList(String[] ids)

Produce a string form of an idList from an array of normalized ids.

private static String
mkIdListAsEntered(String[] externalIds)

Produce an id list from an array of ids in external form

public static String

Returns:

the result.
mkQualifiedName(String id1, String id2)

Produce a delimited two part qualified name from two un-delimited identifiers.

public static String
mkQualifiedName(String[] ids)

Make a string form of a qualified name from the array of ids provided.

public static String

Returns:

the delimited identifier.
normalToDelimited(String id)

Produce a delimited form of a normal value.

public static String[][]
parseDbClassPath(String input)

Scan a database classpath from the string provided.

private static String
parseId(StringReader r, boolean
true means return ids in nomral form, false means return them as they were entered.

Raise an exception if the first thing in the StringReader is not a valid id.

normalize)

Read an id from the StringReader provided.

public static String[]
parseIdList(String p)

Scan a list of comma separated SQL identifiers from the string provided.

private static String[]
parseIdList(StringReader r, boolean
true means return ids in nomral form, false means return them as they were entered.
normalize)

Parse a list of comma separated SQL identifiers returning them a as elements in an array.

public static String[]

Returns:

An array of strings made by breaking the input string at its dots, '.'.
parseMultiPartSQLIdentifier(String
The string to be parsed
s)

Parse a multi-part (dot separated) SQL identifier form the String provided.

private static String[]

Returns:

An array of strings made by breaking the input string at its dots, '.'.
parseMultiPartSQLIdentifier(StringReader
The multi-part identifier to be parsed
r)

private static String

Returns:

the value of the identifer or a delimited identifier
parseQId(StringReader
Quoted identifier to parse.
r, boolean
If true return a delimited identifer, otherwise return the identifier's value.
normalize)

Parse a delimited (quoted) identifier returning either the value of the identifier or a delimited identifier.

public static String

Returns:

the role name to use (internal, case normal form).
parseRoleId(String
role identifier to check (SQL form, has possible quoting)
roleName)

Parse role identifier to internal, case normal form.

public static String
parseSQLIdentifier(String s)

Parse a SQL identifier from the String provided.

private static String

Returns:

the value of the identifer or a delimited identifier
parseUnQId(StringReader
Regular identifier to parse.
r, boolean
If true return the identifer converted to a single case, otherwise return the identifier as entered.
normalize)

Parse a regular identifier (unquoted) returning returning either the value of the identifier or a delimited identifier.

public static String
pruneDups(String
a list of ids in external form.
l)

Return an IdList with all the duplicate ids removed

public static String
SQLIdentifier2CanonicalPropertyUsername(String authid)

Given a case normal form SQL authorization identifier, convert it to a form that may be compared with the username of Derby builtin authentication, which uses Java properties of the form derby.user.

private static String
vectorToIdList(Vector<String> v, boolean
True means the ids in v are in normal form and false means they are in external form.
normal)

Return an idList in external form with one id for every element of v. If v has no elements, return null.

private static void
verifyEmpty(Reader r)

Verify the read is empty (no more characters in its stream).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DBCP_SCHEMA_NAMEback to summary
public static final int DBCP_SCHEMA_NAME

Index of the schema name in a jar name on a db classpath

DBCP_SQL_JAR_NAMEback to summary
public static final int DBCP_SQL_JAR_NAME

Index of the sql jar name in a jar name on a db classpath

Constructor Detail

IdUtilback to summary
public IdUtil()

Method Detail

appendNormalToListback to summary
public static String appendNormalToList(String id, String list) throws StandardException

Append an identifier to a comma separated list of identifiers. The passed in identifier is its normal form, the list contains a list of SQL identifiers, either regular or delimited. This routine takes the easy way out and always appends a delimited identifier.

Returns:String

the list with the id appended in its delimited form.

Exceptions
StandardException:
oops
checkIdentifierLengthLimitback to summary
public static void checkIdentifierLengthLimit(String identifier, int identifier_length_limit) throws StandardException

Check that identifier is not too long

Parameters
identifier:String

identifier (in case normal form) to check

identifier_length_limit:int

maximum legal length

Exceptions
StandardException:
normal error policy
deleteIdback to summary
public static String deleteId(String id, String list) throws StandardException

Delete an normal value from a list of SQL identifiers. The returned list maintains its remaining identifiers in the format they were upon entry to the call.

Parameters
id:String

an id in normal form (quotes removed, upshifted if regular)

list:String

a comma separated list of ids in external form (possibly delmited or not upshifted).

Returns:String

the list with the id deleted or null if the resulting list has no ids. If 'id' is not on 'list' this returns list unchanged. If list becomes empty after the removal null is returned.

Exceptions
StandardException:
oops.
dupsback to summary
public static String dups(String[] l)

Return an IdList with all the ids that are repeated in l.

Parameters
l:String[]

a list of ids in normal form.

getUserAuthorizationIdback to summary
public static String getUserAuthorizationId(String userName) throws StandardException

Map userName to authorizationId in its normal form.

Exceptions
StandardException:
on error or userName is null
getUserNameFromURLPropsback to summary
public static String getUserNameFromURLProps(Properties params)

Get user name from URL properties (key user) without any transformation. If the user property does not exist or is set to the empty string then Property.DEFAULT_USER_NAME is returned.

See Also
Property#DEFAULT_USER_NAME
idCharback to summary
private static boolean idChar(boolean first, int c)
idOnListback to summary
public static boolean idOnList(String id, String list) throws StandardException

Return true if the normalized value of an indentifier is on the list of SQL identifiers provided.

Parameters
id:String

an id in normal form

list:String

a list of ids in external form.

Exceptions
StandardException:
oops.
intersectback to summary
public static String intersect(String[] l1, String[] l2)

Return an IdList with all the ids that in l1 and l2 or null if not ids are on both lists.

Parameters
l1:String[]

An array of ids in normal form

l2:String[]

An array of ids in nomral form

mkIdListback to summary
public static String mkIdList(String[] ids)

Produce a string form of an idList from an array of normalized ids.

mkIdListAsEnteredback to summary
private static String mkIdListAsEntered(String[] externalIds)

Produce an id list from an array of ids in external form

mkQualifiedNameback to summary
public static String mkQualifiedName(String id1, String id2)

Produce a delimited two part qualified name from two un-delimited identifiers.

Returns:String

the result.

mkQualifiedNameback to summary
public static String mkQualifiedName(String[] ids)

Make a string form of a qualified name from the array of ids provided.

normalToDelimitedback to summary
public static String normalToDelimited(String id)

Produce a delimited form of a normal value.

Returns:String

the delimited identifier.

parseDbClassPathback to summary
public static String[][] parseDbClassPath(String input) throws StandardException

Scan a database classpath from the string provided. This returns an array with one qualified name per entry on the classpath. The constants above describe the content of the returned names. This raises an an exception if the string does not contain a valid database class path. 

      classpath := item[:item]*
	  item := id.id

	  In the syntax braces ([]) show grouping. '*' means repeat 0 or more times.
	  The syntax for id is defined in IdUtil.

Classpath returned is a two part name.
If the class path is empty then this returns an array of zero length.
Exceptions
StandardException:
Oops
parseIdback to summary
private static String parseId(StringReader r, boolean normalize) throws StandardException

Read an id from the StringReader provided.

Parameters
normalize:boolean

true means return ids in nomral form, false means return them as they were entered.

Raise an exception if the first thing in the StringReader is not a valid id.

Exceptions
StandardException:
Ooops.
parseIdListback to summary
public static String[] parseIdList(String p) throws StandardException

Scan a list of comma separated SQL identifiers from the string provided. This returns an array with containing the normalized forms of the identifiers. This raises an an exception if the string does not contain a valid list of names.

Exceptions
StandardException:
Oops
parseIdListback to summary
private static String[] parseIdList(StringReader r, boolean normalize) throws StandardException

Parse a list of comma separated SQL identifiers returning them a as elements in an array.

Parameters
normalize:boolean

true means return ids in nomral form, false means return them as they were entered.

Exceptions
StandardException:
Oops
parseMultiPartSQLIdentifierback to summary
public static String[] parseMultiPartSQLIdentifier(String s) throws StandardException

Parse a multi-part (dot separated) SQL identifier form the String provided. Raise an excepion if the string does not contain valid SQL indentifiers. The returned String array contains the normalized form of the identifiers.

Parameters
s:String

The string to be parsed

Returns:String[]

An array of strings made by breaking the input string at its dots, '.'.

Exceptions
StandardException:
Oops
parseMultiPartSQLIdentifierback to summary
private static String[] parseMultiPartSQLIdentifier(StringReader r) throws StandardException
Parameters
r:StringReader

The multi-part identifier to be parsed

Returns:String[]

An array of strings made by breaking the input string at its dots, '.'.

Exceptions
StandardException:
Oops
parseQIdback to summary
private static String parseQId(StringReader r, boolean normalize) throws IOException, StandardException

Parse a delimited (quoted) identifier returning either the value of the identifier or a delimited identifier.

Parameters
r:StringReader

Quoted identifier to parse.

normalize:boolean

If true return a delimited identifer, otherwise return the identifier's value.

Returns:String

the value of the identifer or a delimited identifier

Exceptions
IOException:
Error accessing value
StandardException:
Error parsing identifier.
parseRoleIdback to summary
public static String parseRoleId(String roleName) throws StandardException

Parse role identifier to internal, case normal form. It should not be NONE nor exceed Limits.MAX_IDENTIFIER_LENGTH.

Parameters
roleName:String

role identifier to check (SQL form, has possible quoting)

Returns:String

the role name to use (internal, case normal form).

Exceptions
StandardException:
normal error policy
parseSQLIdentifierback to summary
public static String parseSQLIdentifier(String s) throws StandardException

Parse a SQL identifier from the String provided. Raise an excepion if the string does not contain a valid SQL indentifier. The returned String contains the normalized form of the identifier.

Exceptions
StandardException:
Oops
parseUnQIdback to summary
private static String parseUnQId(StringReader r, boolean normalize) throws IOException, StandardException

Parse a regular identifier (unquoted) returning returning either the value of the identifier or a delimited identifier. Ensures that all characters in the identifer are valid for a regular identifier.

Parameters
r:StringReader

Regular identifier to parse.

normalize:boolean

If true return the identifer converted to a single case, otherwise return the identifier as entered.

Returns:String

the value of the identifer or a delimited identifier

Exceptions
IOException:
Error accessing value
StandardException:
Error parsing identifier.
pruneDupsback to summary
public static String pruneDups(String l) throws StandardException

Return an IdList with all the duplicate ids removed

Parameters
l:String

a list of ids in external form.

Exceptions
StandardException:
Oops.
SQLIdentifier2CanonicalPropertyUsernameback to summary
public static String SQLIdentifier2CanonicalPropertyUsername(String authid)

Given a case normal form SQL authorization identifier, convert it to a form that may be compared with the username of Derby builtin authentication, which uses Java properties of the form derby.user.<username>.

The returned form is suitable for comparing against the property string, cf. systemPropertiesExistsBuiltinUser.

E.g.: 

 Argument -> Return
 ------------------
 EVE      -> eve       [will match Java property: derby.user.eve]
 eVe      -> "eVe"     [will match Java property: derby.user."eVe"]
 "eve"    -> """eve""" [will match Java property: derby.user."""eVe"""]
 \eve\    -> "\eve\"   [will match Java property: derby.user."\eve\"]

The latter could look this if specified on a Unix shell command line:

                     -Dderby.user.'"\eve\"'=<password>

Note

The processing of properties specified on the command line do not
interpret backslash as escape in the way done by the
java.util.Properties#load method, so no extra backslash is needed above.
Since parseSQLIdentifier maps many-to-one, the backward mapping is non-unique, so the chosen lower case canonical form is arbitrary, e.g. we will not be able to correctly match the non-canonical: 

                     [Java property: derby.user.eVe]
since this is internally EVE (but see DERBY-3150), and maps back as eve after the rules above.
See Also
org.apache.derby.iapi.services.property.PropertyUtil#propertiesContainsBuiltinUser, org.apache.derby.iapi.services.property.PropertyUtil#systemPropertiesExistsBuiltinUser
vectorToIdListback to summary
private static String vectorToIdList(Vector<String> v, boolean normal)

Return an idList in external form with one id for every element of v. If v has no elements, return null.

Parameters
normal:boolean

True means the ids in v are in normal form and false means they are in external form.

verifyEmptyback to summary
private static void verifyEmpty(Reader r) throws StandardException

Verify the read is empty (no more characters in its stream).