Class IdUtil

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

public abstract class IdUtil extends 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:

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

    • 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:
    • 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:
  • Constructor Details

    • IdUtil

      public IdUtil()
  • Method Details

    • normalToDelimited

      public static String normalToDelimited(String id)
      Produce a delimited form of a normal value.
      Returns:
      the delimited identifier.
    • mkQualifiedName

      public static String mkQualifiedName(String id1, String id2)
      Produce a delimited two part qualified name from two un-delimited identifiers.
      Returns:
      the result.
    • mkQualifiedName

      public static String mkQualifiedName(String[] ids)
      Make a string form of a qualified name from the array of ids provided.
    • parseMultiPartSQLIdentifier

      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 - 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 String[] parseMultiPartSQLIdentifier(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 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.
      Throws:
      StandardException - Oops
    • parseId

      private static String parseId(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 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:
    • parseUnQId

      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 - 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:
      IOException - Error accessing value
      StandardException - Error parsing identifier.
    • idChar

      private static boolean idChar(boolean first, int c)
    • parseQId

      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 - 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:
      IOException - Error accessing value
      StandardException - Error parsing identifier.
    • verifyEmpty

      private static void verifyEmpty(Reader r) throws StandardException
      Verify the read is empty (no more characters in its stream).
      Parameters:
      r -
      Throws:
      StandardException
    • parseDbClassPath

      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.
      Throws:
      StandardException - Oops
    • parseIdList

      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.
      Throws:
      StandardException - Oops
    • parseIdList

      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 - true means return ids in nomral form, false means return them as they were entered.
      Throws:
      StandardException - Oops
    • intersect

      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 - An array of ids in normal form
      l2 - An array of ids in nomral form
    • vectorToIdList

      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 - True means the ids in v are in normal form and false means they are in external form.
    • getUserAuthorizationId

      public static String getUserAuthorizationId(String userName) throws StandardException
      Map userName to authorizationId in its normal form.
      Throws:
      StandardException - on error or userName is null
    • getUserNameFromURLProps

      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:
    • dups

      public static String dups(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 String pruneDups(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 String mkIdList(String[] ids)
      Produce a string form of an idList from an array of normalized ids.
    • mkIdListAsEntered

      private static String mkIdListAsEntered(String[] externalIds)
      Produce an id list from an array of ids in external form
    • idOnList

      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 - an id in normal form
      list - a list of ids in external form.
      Throws:
      StandardException - oops.
    • deleteId

      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 - 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 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:
      the list with the id appended in its delimited form.
      Throws:
      StandardException - oops
    • parseRoleId

      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 - 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(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