Package ptolemy.actor.lib.database

Class DatabaseManager

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class DatabaseManager
extends TypedAtomicActor
    A DatabaseManager. When preinitialized, this actor opens a connection to the specified database. When wrapup() is called, it closes the connection. A user of this class can also separately call getConnection() to open a connection, but then that user must also call closeConnection() when finished.

    This class polls all available JDBC database drivers until one is willing to open the string given by the database parameter. Depending on the driver, this string may be a URL. Some database drivers are packaged with Ptolemy II and available from a vergil process. You can make others available by setting the jdbc.drivers property. For example, when invoking vergil, do something like this: 

      export JAVAFLAGS=-Djdbc.drivers=com.mysql.jdbc.Driver:bad.tast.ourDriver
  $PTII/bin/vergil -verbose
    The above lists two drivers, in order of preference, separated by a ":". More information can be found at http://download.oracle.com/javase/6/docs/api/java/sql/DriverManager.html
    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (eal)

    • Field Detail

      • database

        public StringParameter database
        JDBC connection string to access the database. This always starts with "jdbc:driver", where the specific driver chosen determines how to interpret fields in the rest of the string. For example, 
            jdbc:oracle:thin:@buffy.eecs.berkeley.edu:1521:acgeecs
        specifies a thin client for an Oracle database located at host buffy.eecs.berkeley.edu, which listens on port 1521. The "acgeecs" is the database name. Another example is 
            jdbc:mysql://localhost:3306/space
        which specifies a MySQL database on the local host, where "space" is the name of the database.

      • passwordFile

        public FileParameter passwordFile
        The file that contains the password. If this parameter is non-empty, then it is assumed to refer to a file that contains the password. If this parameter is empty, or names a file that cannot be read, then a dialog is displayed for the user to enter the password. It is up to the user to properly protect the file from unauthorized readers by using the file system permissions. The default value is the empty string, meaning that the dialog will be displayed.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        React to a change in an attribute. This method is called by a contained attribute when its value changes. In this class, if the database or userName is changed, this method closes the connection with the database and forgets the password.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

      • execute

        public java.lang.String execute​(java.lang.String sql)
                         throws IllegalActionException
        Execute the specified SQL statement and return the result as a string. Note that if there is no connection to the database, this will open one. The caller is responsible for calling closeConnection() after this.
        Parameters:
        sql - The query.
        Returns:
        The result as a string.
        Throws:
        IllegalActionException - If the statement fails.

      • executeQuery

        public ArrayToken executeQuery​(java.lang.String sql)
                        throws IllegalActionException
        Execute the SQL query given in the specified string and return an array of record tokens containing the results. Note that if there is no connection to the database, this will open one. The caller is responsible for calling closeConnection() after this.
        Parameters:
        sql - The query.
        Returns:
        An array of record tokens containing the results, which may be empty (zero length), or null if the connection fails or is canceled.
        Throws:
        IllegalActionException - If the query fails.

      • executeUpdate

        public int executeUpdate​(java.lang.String sql,
                         int expectedResult)
                  throws IllegalActionException
        Execute the SQL update given in the specified string and return the number of affected rows or zero if the update does not return anything. Note that if there is no connection to the database, this will open one. The caller is responsible for calling closeConnection() after this.
        Parameters:
        sql - The query.
        expectedResult - If a non-negative number is given here, then the update is not committed unless the result matches.
        Returns:
        The number of rows affected or 0 if the update does not return a value, or -1 if the connection is canceled.
        Throws:
        IllegalActionException - If the query fails or if the result does not match the value of expectedResult.

      • findDatabaseManager

        public static DatabaseManager findDatabaseManager​(java.lang.String name,
                                                  NamedObj actor)
                                           throws IllegalActionException
        Find a database manager with the specified name for the specified actor.
        Parameters:
        name - Database manager name.
        actor - The actor.
        Returns:
        A database manager.
        Throws:
        IllegalActionException - If no database manager is found.

      • getConnection

        public java.sql.Connection getConnection()
                                  throws IllegalActionException
        Get a connection to the database. If one is already open, then simply return that one. Otherwise, use the parameter values and prompt for a password to open a new connection.
        Returns:
        A connection to the database, or null if the user cancels.
        Throws:
        IllegalActionException - If the password file cannot be read and "ptolemy.ptII.isRunningNightlyBuild" property exists and is not empty or if the "ptolemy.ptII.batchMode" property exists and is not empty and the property "ptolemyII.ptII.testingMessageHandler" is not set.