IdUtil (Apache Derby V10.14 Internals)

java.lang.Object
- org.apache.derby.iapi.util.IdUtil

public abstract class IdUtil
extends java.lang.Object

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:

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

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`DBCP_SCHEMA_NAME`	Index of the schema name in a jar name on a db classpath
`static int`	`DBCP_SQL_JAR_NAME`	Index of the sql jar name in a jar name on a db classpath

Constructor Summary

Constructors
Constructor Description

IdUtil()

Constructors
Constructor	Description
`IdUtil()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static java.lang.String`	`appendNormalToList(java.lang.String id, java.lang.String list)`	Append an identifier to a comma separated list of identifiers.
`static void`	`checkIdentifierLengthLimit(java.lang.String identifier, int identifier_length_limit)`	Check that identifier is not too long
`static java.lang.String`	`deleteId(java.lang.String id, java.lang.String list)`	Delete an normal value from a list of SQL identifiers.
`static java.lang.String`	`dups(java.lang.String[] l)`	Return an IdList with all the ids that are repeated in l.
`static java.lang.String`	`getUserAuthorizationId(java.lang.String userName)`	Map userName to authorizationId in its normal form.
`static java.lang.String`	`getUserNameFromURLProps(java.util.Properties params)`	Get user name from URL properties (key user) without any transformation.
`private static boolean`	`idChar(boolean first, int c)`
`static boolean`	`idOnList(java.lang.String id, java.lang.String list)`	Return true if the normalized value of an indentifier is on the list of SQL identifiers provided.
`static java.lang.String`	`intersect(java.lang.String[] l1, java.lang.String[] l2)`	Return an IdList with all the ids that in l1 and l2 or null if not ids are on both lists.
`static java.lang.String`	`mkIdList(java.lang.String[] ids)`	Produce a string form of an idList from an array of normalized ids.
`private static java.lang.String`	`mkIdListAsEntered(java.lang.String[] externalIds)`	Produce an id list from an array of ids in external form
`static java.lang.String`	`mkQualifiedName(java.lang.String[] ids)`	Make a string form of a qualified name from the array of ids provided.
`static java.lang.String`	`mkQualifiedName(java.lang.String id1, java.lang.String id2)`	Produce a delimited two part qualified name from two un-delimited identifiers.
`static java.lang.String`	`normalToDelimited(java.lang.String id)`	Produce a delimited form of a normal value.
`static java.lang.String[][]`	`parseDbClassPath(java.lang.String input)`	Scan a database classpath from the string provided.
`private static java.lang.String`	`parseId(java.io.StringReader r, boolean normalize)`	Read an id from the StringReader provided.
`private static java.lang.String[]`	`parseIdList(java.io.StringReader r, boolean normalize)`	Parse a list of comma separated SQL identifiers returning them a as elements in an array.
`static java.lang.String[]`	`parseIdList(java.lang.String p)`	Scan a list of comma separated SQL identifiers from the string provided.
`private static java.lang.String[]`	`parseMultiPartSQLIdentifier(java.io.StringReader r)`
`static java.lang.String[]`	`parseMultiPartSQLIdentifier(java.lang.String s)`	Parse a multi-part (dot separated) SQL identifier form the String provided.
`private static java.lang.String`	`parseQId(java.io.StringReader r, boolean normalize)`	Parse a delimited (quoted) identifier returning either the value of the identifier or a delimited identifier.
`static java.lang.String`	`parseRoleId(java.lang.String roleName)`	Parse role identifier to internal, case normal form.
`static java.lang.String`	`parseSQLIdentifier(java.lang.String s)`	Parse a SQL identifier from the String provided.
`private static java.lang.String`	`parseUnQId(java.io.StringReader r, boolean normalize)`	Parse a regular identifier (unquoted) returning returning either the value of the identifier or a delimited identifier.
`static java.lang.String`	`pruneDups(java.lang.String l)`	Return an IdList with all the duplicate ids removed
`static java.lang.String`	`SQLIdentifier2CanonicalPropertyUsername(java.lang.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>.
`private static java.lang.String`	`vectorToIdList(java.util.Vector<java.lang.String> v, boolean normal)`	Return an idList in external form with one id for every element of v.
`private static void`	`verifyEmpty(java.io.Reader r)`	Verify the read is empty (no more characters in its stream).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DBCP_SCHEMA_NAME
```
public static final int DBCP_SCHEMA_NAME
```
    Index of the schema name in a jar name on a db classpath
    
    See Also:
    
    Constant Field Values
  - DBCP_SQL_JAR_NAME
```
public static final int DBCP_SQL_JAR_NAME
```
    Index of the sql jar name in a jar name on a db classpath
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - IdUtil
```
public IdUtil()
```
- Method Detail
  - normalToDelimited
```
public static java.lang.String normalToDelimited(java.lang.String id)
```
    Produce a delimited form of a normal value.
    
    Returns:
    
    the delimited identifier.
  - mkQualifiedName
```
public static java.lang.String mkQualifiedName(java.lang.String id1,
                                               java.lang.String id2)
```
    Produce a delimited two part qualified name from two un-delimited identifiers.
    
    Returns:
    
    the result.
  - mkQualifiedName
```
public static java.lang.String mkQualifiedName(java.lang.String[] ids)
```
    Make a string form of a qualified name from the array of ids provided.
  - parseMultiPartSQLIdentifier
```
public static java.lang.String[] parseMultiPartSQLIdentifier(java.lang.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 - The string to be parsed
    
    Returns:
    
    An array of strings made by breaking the input string at its dots, '.'.
    
    Throws:
    
    StandardException - Oops
  - parseMultiPartSQLIdentifier
```
private static java.lang.String[] parseMultiPartSQLIdentifier(java.io.StringReader r)
                                                       throws StandardException
```
    Parameters:
    
    r - The multi-part identifier to be parsed
    
    Returns:
    
    An array of strings made by breaking the input string at its dots, '.'.
    
    Throws:
    
    StandardException - Oops
  - parseSQLIdentifier
```
public static java.lang.String parseSQLIdentifier(java.lang.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.
    
    Throws:
    
    StandardException - Oops
  - parseId
```
private static java.lang.String parseId(java.io.StringReader r,
                                        boolean normalize)
                                 throws StandardException
```
    Read an id from the StringReader provided.
    
    Parameters:
    
    normalize - 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.
    
    Throws:
    
    StandardException - Ooops.
  - SQLIdentifier2CanonicalPropertyUsername
```
public static java.lang.String SQLIdentifier2CanonicalPropertyUsername(java.lang.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:
    
    PropertyUtil.propertiesContainsBuiltinUser(java.util.Properties, java.lang.String), PropertyUtil.systemPropertiesExistsBuiltinUser(java.lang.String)
  - parseUnQId
```
private static java.lang.String parseUnQId(java.io.StringReader r,
                                           boolean normalize)
                                    throws java.io.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 - Regular identifier to parse.
    
    normalize - If true return the identifer converted to a single case, otherwise return the identifier as entered.
    
    Returns:
    
    the value of the identifer or a delimited identifier
    
    Throws:
    
    java.io.IOException - Error accessing value
    
    StandardException - Error parsing identifier.
  - idChar
```
private static boolean idChar(boolean first,
                              int c)
```
  - parseQId
```
private static java.lang.String parseQId(java.io.StringReader r,
                                         boolean normalize)
                                  throws java.io.IOException,
                                         StandardException
```
    Parse a delimited (quoted) identifier returning either the value of the identifier or a delimited identifier.
    
    Parameters:
    
    r - Quoted identifier to parse.
    
    normalize - If true return a delimited identifer, otherwise return the identifier's value.
    
    Returns:
    
    the value of the identifer or a delimited identifier
    
    Throws:
    
    java.io.IOException - Error accessing value
    
    StandardException - Error parsing identifier.
  - verifyEmpty
```
private static void verifyEmpty(java.io.Reader r)
                         throws StandardException
```
    Verify the read is empty (no more characters in its stream).
    
    Parameters:
    
    r -
    
    Throws:
    
    StandardException
  - parseDbClassPath
```
public static java.lang.String[][] parseDbClassPath(java.lang.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.
    Throws:
    
    StandardException - Oops
  - parseIdList
```
public static java.lang.String[] parseIdList(java.lang.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.
    
    Throws:
    
    StandardException - Oops
  - parseIdList
```
private static java.lang.String[] parseIdList(java.io.StringReader r,
                                              boolean normalize)
                                       throws StandardException
```
    Parse a list of comma separated SQL identifiers returning them a as elements in an array.
    
    Parameters:
    
    normalize - true means return ids in nomral form, false means return them as they were entered.
    
    Throws:
    
    StandardException - Oops
  - intersect
```
public static java.lang.String intersect(java.lang.String[] l1,
                                         java.lang.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 - An array of ids in normal form
    
    l2 - An array of ids in nomral form
  - vectorToIdList
```
private static java.lang.String vectorToIdList(java.util.Vector<java.lang.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 - True means the ids in v are in normal form and false means they are in external form.
  - getUserAuthorizationId
```
public static java.lang.String getUserAuthorizationId(java.lang.String userName)
                                               throws StandardException
```
    Map userName to authorizationId in its normal form.
    
    Throws:
    
    StandardException - on error or userName is null
  - getUserNameFromURLProps
```
public static java.lang.String getUserNameFromURLProps(java.util.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
  - dups
```
public static java.lang.String dups(java.lang.String[] l)
```
    Return an IdList with all the ids that are repeated in l.
    
    Parameters:
    
    l - a list of ids in normal form.
  - pruneDups
```
public static java.lang.String pruneDups(java.lang.String l)
                                  throws StandardException
```
    Return an IdList with all the duplicate ids removed
    
    Parameters:
    
    l - a list of ids in external form.
    
    Throws:
    
    StandardException - Oops.
  - mkIdList
```
public static java.lang.String mkIdList(java.lang.String[] ids)
```
    Produce a string form of an idList from an array of normalized ids.
  - mkIdListAsEntered
```
private static java.lang.String mkIdListAsEntered(java.lang.String[] externalIds)
```
    Produce an id list from an array of ids in external form
  - idOnList
```
public static boolean idOnList(java.lang.String id,
                               java.lang.String list)
                        throws StandardException
```
    Return true if the normalized value of an indentifier is on the list of SQL identifiers provided.
    
    Parameters:
    
    id - an id in normal form
    
    list - a list of ids in external form.
    
    Throws:
    
    StandardException - oops.
  - deleteId
```
public static java.lang.String deleteId(java.lang.String id,
                                        java.lang.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 - an id in normal form (quotes removed, upshifted if regular)
    
    list - a comma separated list of ids in external form (possibly delmited or not upshifted).
    
    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.
    
    Throws:
    
    StandardException - oops.
  - appendNormalToList
```
public static java.lang.String appendNormalToList(java.lang.String id,
                                                  java.lang.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:
    
    the list with the id appended in its delimited form.
    
    Throws:
    
    StandardException - oops
  - parseRoleId
```
public static java.lang.String parseRoleId(java.lang.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 - role identifier to check (SQL form, has possible quoting)
    
    Returns:
    
    the role name to use (internal, case normal form).
    
    Throws:
    
    StandardException - normal error policy
  - checkIdentifierLengthLimit
```
public static void checkIdentifierLengthLimit(java.lang.String identifier,
                                              int identifier_length_limit)
                                       throws StandardException
```
    Check that identifier is not too long
    
    Parameters:
    
    identifier - identifier (in case normal form) to check
    
    identifier_length_limit - maximum legal length
    
    Throws:
    
    StandardException - normal error policy

Class IdUtil

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DBCP_SCHEMA_NAME

DBCP_SQL_JAR_NAME

Constructor Detail

IdUtil

Method Detail

normalToDelimited

mkQualifiedName

mkQualifiedName

parseMultiPartSQLIdentifier

parseMultiPartSQLIdentifier

parseSQLIdentifier

parseId

SQLIdentifier2CanonicalPropertyUsername

parseUnQId

idChar

parseQId

verifyEmpty

parseDbClassPath

parseIdList

parseIdList

intersect

vectorToIdList

getUserAuthorizationId

getUserNameFromURLProps

dups

pruneDups

mkIdList

mkIdListAsEntered

idOnList

deleteId

appendNormalToList

parseRoleId

checkIdentifierLengthLimit