Module org.postgresql.pljava.internal
Package org.postgresql.pljava.management

Class SQLDeploymentDescriptor

  • public class SQLDeploymentDescriptor
extends Object
    This class deals with parsing and executing the deployment descriptor as defined in ISO/IEC 9075-13:2003. It has the following format:
    
 <descriptor file> ::=
 SQLActions <left bracket> <right bracket> <equal sign>
 { [ <double quote> <action group> <double quote>
   [ <comma> <double quote> <action group> <double quote> ] ] }

 <action group> ::=
     <install actions>
   | <remove actions>
 
 <install actions> ::=
   BEGIN INSTALL [ <command> <semicolon> ]... END INSTALL

 <remove actions> ::=
   BEGIN REMOVE [ <command> <semicolon> ]... END REMOVE

 <command> ::=
     <SQL statement>
   | <implementor block>

 <SQL statement> ::= <SQL token>...
 
 <implementor block> ::=
   BEGIN <implementor name> <SQL token>... END <implementor name>

 <implementor name> ::= <identifier>

 <SQL token> ::= an SQL lexical unit specified by the term "<token>" in
 Subclause 5.2, "<token>" and "<separator>", in ISO/IEC 9075-2.

    Note: this parser departs from the specification for <descriptor file> in the following ways:

    • Per ISO/IEC 9075-13, an <SQL statement> (not wrapped as an <implementor block>), may be one of only a few types of statement: declaring a procedure, function, or type; granting USAGE on a type, or EXECUTE on a procedure or function; declaring the ordering of a type. Any SQL that is not one of those, or does not use the exact ISO/IEC 9075 syntax, is allowed only within an <implementor block>. This parser does not enforce that restriction. This behavior is strictly more lax than the spec, and will not reject any standards-conformant descriptor file.
    • Officially, an <implementor name> is an SQL identifier and may have any of the forms defined in 9075-2 subclause 5.2. This parser (a) only recognizes the <regular identifier> form (that is, non-double-quoted, no Unicode escape, matched case-insensitively), and (b) replaces the SQL allowable-character rules <identifier start> and <identifier extend> with the similar but nonidentical Java rules Character.isJavaIdentifierStart(char) and Character.isJavaIdentifierPart(char) (which do not work for characters in the supplementary character range). In unlikely cases this could lead to rejecting a deployment descriptor that in fact conforms to the standard.
    • Through PL/Java 1.4.3, this parser has not recognized -- as the start of an SQL comment (which it is), and has recognized //, which isn't.
    • Also through PL/Java 1.4.3, all whitespace (outside of quoted literals and identifiers) has been collapsed to a single SPACE, which would run afoul of the SQL rules for quoted literal/identifier continuation, if a deployment descriptor were ever to use that.

    The most conservative way to generate a deployment descriptor for PL/Java's consumption is to wrap all commands as <implementor block> and ensure that any <implementor name> is both a valid Java identifier and a valid SQL <regular identifier> containing nothing from the supplementary character range.

    Author:
    Thomas Hallgren, Chapman Flack

    • Constructor Detail

      • SQLDeploymentDescriptor

        public SQLDeploymentDescriptor​(String descImage)
                        throws ParseException
        Parses the deployment descriptor descImage into a series of Command objects each having an SQL command and, if present, an <implementor name>. The install and remove blocks are remembered for later execution with calls to install() and remove().
        Parameters:
        descImage - The image to parse
        Throws:
        ParseException - If a parse error is encountered

    • Method Detail

      • install

        public void install​(Connection conn)
             throws SQLException
        Executes the INSTALL actions.
        Parameters:
        conn - The connection to use for the execution.
        Throws:
        SQLException

      • remove

        public void remove​(Connection conn)
            throws SQLException
        Executes the REMOVE actions.
        Parameters:
        conn - The connection to use for the execution.
        Throws:
        SQLException

      • toString

        public String toString()
        Returns the original image.
        Overrides:
        toString in class Object