Class 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:

    1. Unicode escape sequences in ids are not supported.
    2. 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()  
    • 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