Modified:
trunk/connector-mxj/CHANGES
trunk/connector-mxj/README.1st
trunk/connector-mxj/README.txt
trunk/connector-mxj/index.html
trunk/connector-mxj/src/com/mysql/management/driverlaunched/ServerLauncherSocketFactory.java
Log:
2007-07-09 - Changed embedded doc files to point to published docs at:
http://dev.mysql.com/doc/refman/5.0/en/connector-mxj.html
2007-07-03 - Fixed URL-style shutdown issue where undetermined running port
would be interpreted as wrong and thus would throw. Now warns.
Modified: trunk/connector-mxj/CHANGES
===================================================================
--- trunk/connector-mxj/CHANGES 2007-06-30 09:43:15 UTC (rev 102)
+++ trunk/connector-mxj/CHANGES 2007-07-09 07:52:26 UTC (rev 103)
@@ -1,8 +1,14 @@
# Changelog
# $Id: CHANGES,v 1.14 2005/10/25 19:11:16 eherman Exp $
+2007-07-09 - Changed embedded doc files to point to published docs at:
+ http://dev.mysql.com/doc/refman/5.0/en/connector-mxj.html
+
+2007-07-03 - Fixed URL-style shutdown issue where undetermined running port
+ would be interpreted as wrong and thus would throw. Now warns.
+
2007-06-30 - added method MysqldResource.deployFiles() so that db files may be
- extracted without started the databse
+ extracted without started the database
2007-06-25 - included URL re-conneciton optimization
- added TODO entries in _dev_notes.txt
Modified: trunk/connector-mxj/README.1st
===================================================================
--- trunk/connector-mxj/README.1st 2007-06-30 09:43:15 UTC (rev 102)
+++ trunk/connector-mxj/README.1st 2007-07-09 07:52:26 UTC (rev 103)
@@ -53,6 +53,6 @@
DOCUMENTATION
-Please work through the Getting Started guide (README.txt or index.html) to see
-how to use the software.
+Documentation can be found at:
+http://dev.mysql.com/doc/refman/5.0/en/connector-mxj.html
Modified: trunk/connector-mxj/README.txt
===================================================================
--- trunk/connector-mxj/README.txt 2007-06-30 09:43:15 UTC (rev 102)
+++ trunk/connector-mxj/README.txt 2007-07-09 07:52:26 UTC (rev 103)
@@ -1,680 +1,3 @@
-1. MySQL Connector/MXJ
+MySQL Connector/MXJ documenation is posted here:
+http://dev.mysql.com/doc/refman/5.0/en/connector-mxj.html
- ----------------------------------------------------------------------
-
- 1.1. Introduction
-
- [EH] Some of the steps documented are very basic (like requiring a JDK);
- feel free to skip over the obvious ones, and please understand that I've
- tried to be complete, I'm not trying to talk down to the audience. -- Eric
- Herman 2004 Aug 20
-
- MySQL Connector/MXJ is a Java Utility package for deploying and managing a
- MySQL database. Connector/MXJ may be bundled in to an existing Java
- application or may be deployed as a JMX MBean. Deploying and using MySQL
- can be as easy as adding an additional parameter to the JDBC connection
- url, which will result in the database being started when the first
- connection is made. This makes it easy for Java developers to deploy
- applications which require a database by reducing installation barriers
- for their end-users.
-
- MySQL Connector/MXJ makes the MySQL database appear to be a java-based
- component. It does this by determining what platform the system is running
- on, selecting the appropriate binary, and launching the executable. It
- will also optionally deploy an initial database, with any specified
- parameters.
-
- As a JMX MBean, MySQL Connector/MXJ requires a JMX v1.2 compliant MBean
- container, such as JBoss version 4. The MBean will uses the standard JMX
- management APIs to present (and allow the setting of) parameters which are
- appropriate for that platform.
-
- Included are instructions for use with a JDBC driver and deploying as a
- JMX MBean to JBoss.
-
- You can download sources and binaries from:
- http://dev.mysql.com/downloads/connector/mxj/
-
- This an beta release and feedback is welcome and encouraged.
-
- Please send questions or comments to java@stripped.
-
- 1.2. Support Platforms:
-
- o
-
- Linux, i386
-
- o
-
- Windows NT, x86
-
- o
-
- Windows 2000, x86
-
- o
-
- Windows XP, x86
-
- o
-
- Solaris 9, SPARC 32
-
- 1.3. JUnit Test Requirements
-
- The best way to ensure that your platform is supported is to run the JUnit
- tests.
-
- The first thing to do is make sure that the components will work on the
- platform. Since the ''MysqldResource'' class is really a wrapper for a
- native version of MySQL, not all platforms are supported. At the time of
- this writing, Linux on the i386 architecture has been tested and seems to
- work quite well, as does OS X v10.3. There has been limited testing on
- Windows and Solaris.
-
- Requirements:
-
-
-
- JDK-1.4 or newer (or the JRE if you aren't going to be compiling the
- source or JSPs).
-
-
-
- MySQL Connector/J version 3.1 or newer (from
- http://dev.mysql.com/downloads/connector/j/ ) installed and available
- via your CLASSPATH.
-
-
-
- The javax.management classes for JMX version 1.2.1, these are present
- in the following application servers:
-
- o
-
- JBoss - 4.0rc1 or newer
-
- o
-
- Apache Tomcat - 5.0 or newer
-
- o
-
- Sun's JMX reference implementation version 1.2.1
- http://java.sun.com/products/JavaManagement/
-
-
-
- Junit 3.8.1 (from http://www.junit.org/)
-
- If building from source, All of the requirements from above, plus:
-
-
-
- Ant version 1.5 or newer (download from http://ant.apache.org/)
-
- 1.4. Running the JUnit Tests
-
-
-
- The tests attempt to launch MySQL on the port 3336. If you have a
- MySQL running, it may conflict, but this isn't very likely since
- thedefault port for MySQL is 3306. However, You may set the
- "c-mxj_test_port" Java property to a port of your choosing.
- Alternatively, you may wish to start by shutting down any instances of
- MySQL you have running on the target machine.
-
- The tests surpress output to the console by default. For verbose
- output, you may set the "c-mxj_test_silent" Java property to "false".
-
-
-
- In order to run the JUnit test suite, the $CLASSPATH must include the
- following:
-
- o
-
- JUnit
-
- o
-
- JMX
-
- o
-
- Connector/J
-
- o
-
- MySQL Connector/MXJ
-
-
-
- If connector-mxj.jar is not present in your download, unzip MySQL
- Connector/MXJ source archive.
-
- cd mysqldjmx
- ant dist
-
-
- Then add $TEMP/cmxj/stage/connector-mxj/connector-mxj.jar to the
- CLASSPATH.
-
-
-
- if you have junit, execute the unit tests. From the command line,
- type:
-
- java junit.textui.TestRunner com.mysql.management.AllTestsSuite
-
-
- The output should look something like this:
-
- .........................................
- .........................................
- ..........
- Time: 259.438
-
- OK (101 tests)
-
-
- Note that the tests are a bit slow near the end, so please be patient.
-
- 1.5. Running as part of the JDBC Driver
-
- A feature of the MySQL Connector/J JDBC driver is the ability to specify a
- ''SocketFactory'' as a parameter in the JDBC connection string. MySQL
- Connector/MXJ includes a custom SocketFactory. The SocketFactory will,
- upon the first connection, deploy and launch the MySQL database. The
- SocketFactory also exposes a ''shutdown'' method.
-
- To try it specify the ''socketFactory'' parameter on the JDBC connection
- string with a value equal to
- ''com.mysql.management.driverlaunched.ServerLauncherSocketFactory''
-
- In the following example, we have a program which creates a connection,
- executes a query, and prints the result to the System.out. The MySQL
- database will be deployed and started as part of the connection process,
- and shutdown as part of the finally block.
-
- import java.sql.Connection;
- import java.sql.DriverManager;
- import java.sql.ResultSet;
- import java.sql.Statement;
-
- import com.mysql.management.driverlaunched.ServerLauncherSocketFactory;
-
- public class ConnectorMXJTestExample {
- public static void main(String[] args) throws Exception {
- String hostColonPort = "localhost:3336";
-
- String driver = com.mysql.jdbc.Driver.class.getName();
- String url = "jdbc:mysql://" + hostColonPort + "/" + "?"
- + "socketFactory="
- + ServerLauncherSocketFactory.class.getName();
- String userName = "root";
- String password = "";
-
- Class.forName(driver);
- Connection conn = null;
- try {
- conn = DriverManager.getConnection(url, userName, password);
- Statement stmt = conn.createStatement();
- ResultSet rs = stmt.executeQuery("SELECT VERSION()");
- rs.next();
- String version = rs.getString(1);
- rs.close();
- stmt.close();
-
- System.out.println("------------------------");
- System.out.println(version);
- System.out.println("------------------------");
- } finally {
- try {
- conn.close();
- } catch (Exception e) {
- e.printStackTrace();
- }
- ServerLauncherSocketFactory.shutdown(hostColonPort);
- }
- }
- }
-
-
- To run the above program, be sure to have connector-mxj.jar and
- Connector/J in the CLASSPATH. Then type:
-
- java ConnectorMXJTestExample
-
-
- Of course there are many options we may wish to set for a MySQL database.
- These options may be specified as part of the JDBC connection string
- simply by prefixing each server option with ''server.''. In the following
- example we set three driver parameters and two server parameters:
-
- String url = "jdbc:mysql://" + hostColonPort + "/"
- + "?"
- + "socketFactory="
- + ServerLauncherSocketFactory.class.getName();
- + "&"
- + "cacheServerConfiguration=true"
- + "&"
- + "useLocalSessionState=true"
- + "&"
- + "server.basedir=/opt/myapp/db"
- + "&"
- + "server.datadir=/mnt/bigdisk/myapp/data";
-
-
- 1.6. Running within a Java Object
-
- Have a java application and wish to "embed" a MySQL database, make use of
- the com.mysql.management.MysqldResource class directly. This class may be
- instantiated with the default (no argument) constructor, or by passing in
- a java.io.File object representing the directory you wish the server to be
- "unzipped" into. It may also be instantiated with printstreams for
- "stdout" and "stderr" for logging.
-
- Once instantiated, a java.util.Map, the object will be able to provide a
- java.util.Map of server options appropriate for the platform and version
- of MySQL which you will be using.
-
- The MysqldResource will allow you to "start" MySQL with a java.util.Map of
- server options which you provide, as well as "shutdown" the database. The
- following example shows a simplistic way to embed MySQL in an applicaiton
- using plain java objects:
-
- import com.mysql.management.MysqldResource;
-
- ...
-
- public void startMySQL() {
- File baseDir = new File(ourAppDir, "mysql");
- mysqldResource = new MysqldResource(baseDir);
- Map options = new HashMap();
- options.put("port", "3336");
- String threadName = "OurApp MySQL";
- mysqldResource.start(threadName, options);
- }
-
- public void stopMySQL() {
- if (mysqldResource != null) {
- mysqldResource.shutdown();
- }
- mysqldResource = null;
- }
-
- public java.sql.Connection getConnection() throws Exception {
- String db = "test";
- String url = "jdbc:mysql://localhost:3336/" + db;
- String userName = "root";
- String password = "";
- Class.forName(com.mysql.jdbc.Driver.class.getName());
- return DriverManager.getConnection(url, userName, password);
- }
-
-
- 1.7. The MysqldResource API
-
- Constructors:
-
- o
-
- public MysqldResource(File baseDir, PrintStream out, PrintStream err);
-
- Allows the setting of the "basedir" to deploy the MySQL files to, as
- well as out put streams for standard out and standard err.
-
- o
-
- public MysqldResource(File baseDir);
-
- Allows the setting of the "basedir" to deploy the MySQL files to.
- Output for standard out and standard err are directed to System.out
- and System.err.
-
- o
-
- public MysqldResource();
-
- The basedir is defaulted to a subdirectory of the java.io.tempdir.
- Output for standard out and standard err are directed to System.out
- and System.err;
-
- MysqldResource API includes the following methods:
-
- o
-
- void start(String threadName, Map mysqldArgs);
-
- Deploys and starts MySQL. The "threadName" string is used to name the
- thread which actually performs the execution of the MySQL command
- line. The map is the set of arguments and their values to be passed to
- the command line.
-
- o
-
- void shutdown();
-
- Shuts down the MySQL instance managed by the MysqldResource object.
-
- o
-
- Map getServerOptions();
-
- Returns a map of all the options and their current (or default, if not
- running) options available for the MySQL database.
-
- o
-
- boolean isRunning();
-
- Returns true if the MySQL database is running.
-
- o
-
- boolean isReadyForConnections();
-
- Returns true once the database reports that is is ready for
- connections.
-
- o
-
- void setKillDelay(int millis);
-
- The default "Kill Delay" is 30 seconds. This represents the amount of
- time to wait between the initial request to shutdown and issuing a
- "force kill" if the database has not shutdown by itself.
-
- o
-
- void addCompletionListenser(Runnable listener);
-
- Allows for applications to be notified when the server process
- completes. Each ''listener'' will be fired off in its own thread.
-
- o
-
- String getVersion();
-
- returns the version of MySQL.
-
- o
-
- void setVersion(int MajorVersion, int minorVersion, int patchLevel);
-
- The standard distribution comes with only one version of MySQL
- packaged. However, it is possible to package multiple versions, and
- specify which version to use.
-
- 1.8. Running within a JMX Agent (custom)
-
- If you are not using the SUN Reference implementation of the JMX
- libraries, you should skip this section. Or, if you are deploying to
- JBoss, you also may wish to skip to the next section.
-
- We want to see the MysqldDynamicMBean in action inside of a JMX agent. In
- the com.mysql.management.jmx.sunri package is a custom JMX agent with two
- MBeans:
-
-
- the MysqldDynamicMBean, and
-
-
-
- a com.sun.jdmk.comm.HtmlAdaptorServer, which provides a web interface
- for manipulating the beans inside of a JMX agent.
-
- When this very simple agent is started, it will allow a MySQL database to
- be started and stopped with a web browser.
-
-
-
- Complete the testing of the platform as above.
-
- o
-
- current JDK, JUnit, Connector/J, MySQL Connector/MXJ
-
- o
-
- this section requires the SUN reference implementation of JMX
-
- o
-
- PATH, JAVA_HOME, ANT_HOME, CLASSPATH
-
-
-
- If not building from source, skip to next step
-
- rebuild with the "sunri.present"
-
- ant -Dsunri.present=true dist
- re-run tests:
- java junit.textui.TestRunner com.mysql.management.AllTestsSuite
-
-
-
-
- launch the test agent from the command line:
-
- java com.mysql.management.jmx.sunri.MysqldTestAgentSunHtmlAdaptor &
-
-
-
-
- from a browser:
-
- http://localhost:9092/
-
-
-
-
- under MysqldAgent,
-
- select "name=mysqld"
-
-
-
-
- Observe the MBean View
-
-
-
- scroll to the bottom of the screen press the startMysqld button
-
-
-
- click Back to MBean View
-
-
-
- scroll to the bottom of the screen press stopMysqld button
-
- 10.
-
- kill the java process running the Test Agent (jmx server)
-
- 1.9. Deployment in a standard JMX Agent environment (JBoss)
-
- Once there is confidence that the MBean will function on the platform,
- deploying the MBean inside of a standard JMX Agent is the next step.
- Included are instructions for deploying to JBoss.
-
-
-
- Ensure a current version of java development kit (v1.4.x), see above.
-
- o
-
- Ensure JAVA_HOME is set (JBoss requires JAVA_HOME)
-
- o
-
- Ensure JAVA_HOME/bin is in the PATH (You will NOT need to set
- your CLASSPATH, nor will you need any of the jars used in the
- previous tests).
-
-
-
- Ensure a current version of JBoss (v4.0RC1 or better)
-
- http://www.jboss.org/index.html
- select "Downloads"
- select "jboss-4.0.zip"
- pick a mirror
- unzip ~/dload/jboss-4.0.zip
- create a JBOSS_HOME environment variable set to the unzipped directory
- unix only:
- cd $JBOSS_HOME/bin
- chmod +x *.sh
-
-
-
-
- Deploy (copy) the connector-mxj.jar to $JBOSS_HOME/server/default/lib.
-
-
-
- Deploy (copy) mysql-connector-java-3.1.4-beta-bin.jar to
- $JBOSS_HOME/server/default/lib.
-
-
-
- Create a mxjtest.war directory in $JBOSS_HOME/server/default/deploy.
-
-
-
- Deploy (copy) index.jsp to
- $JBOSS_HOME/server/default/deploy/mxjtest.war.
-
-
-
- Create a mysqld-service.xml file in $JBOSS_HOME/server/default/deploy.
-
- <?xml version="1.0" encoding="UTF-8"?>
- <server>
- <mbean code="com.mysql.management.jmx.jboss.JBossMysqldDynamicMBean"
- name="mysql:type=service,name=mysqld">
- <attribute name="datadir">/tmp/xxx_data_xxx</attribute>
- <attribute name="autostart">true</attribute>
- </mbean>
- </server>
-
-
-
-
- Start jboss:
- o
-
- on unix: $JBOSS_HOME/bin/run.sh
-
- o
-
- on windows: %JBOSS_HOME%\bin\run.bat
-
- Be ready: JBoss sends a lot of output to the screen.
-
-
-
- When JBoss seems to have stopped sending output to the screen, open a
- web browser to: http://localhost:8080/jmx-console
-
- 10.
-
- Scroll down to the bottom of the page in the mysql section, select the
- bulleted mysqld link.
-
- 11.
-
- Observe the JMX MBean View page. MySQL should already be running.
-
- 12.
-
- (If "autostart=true" was set, you may skip this step.) Scroll to the
- bottom of the screen. You may press the Invoke button to stop (or
- start) MySQL observe Operation completed successfully without a return
- value. Click Back to MBean View
-
- 13.
-
- To confirm MySQL is running, open a web browser to
- http://localhost:8080/mxjtest/ and you should see that
-
- SELECT 1
-
- returned with a result of
-
- 1
-
- 14.
-
- Guided by the $JBOSS_HOME/server/default/deploy/mxjtest.war/index.jsp
- you will be able to use MySQL in your Web Application. There is a test
- database and a root user (no password) ready to expirement with. Try
- creating a table, inserting some rows, and doing some selects.
-
- 15.
-
- Shut down MySQL. MySQL will be stopped automatically when JBoss is
- stopped, or: from the browser, scroll down to the bottom of the MBean
- View press the stop service Invoke button to halt the service. Observe
- Operation completed successfully without a return value. Using ps or
- task manager see that MySQL is no longer running
-
- As of 1.0.6-beta version is the ability to have the MBean start the MySQL
- database upon start up. Also, we've taken advantage of the JBoss
- life-cycle extension methods so that the database will gracefully shut
- down when JBoss is shutdown.
-
- 1.10. Installation
-
- If you've worked through the above sections, you've arleady performed
- these steps. But we list them here for quick reference.
-
- Driver Launched:
-
-
-
- Download and unzip Connector/MXJ, add connector-mxj.jar to the
- CLASSPATH
-
-
-
- To the JDBC connection string add the following parameter:
- "socketFactory=" + ServerLauncherSocketFactory.class.getName()
-
- JBoss:
-
-
-
- Download Connector/MXJ copy the connector-mxj.jar file to the
- $JBOSS_HOME/server/default/lib diretory.
-
-
-
- Download Connector/J copy the connector-mxj.jar file to the
- $JBOSS_HOME/server/default/lib diretory.
-
-
-
- Create an MBean service xml file in the
- $JBOSS_HOME/server/default/deploy directory with any attributes set,
- for instance the datadir and autostart.
-
-
-
- Set the JDBC parameters of your web application to use: String driver
- = "com.mysql.jdbc.Driver"; String url =
- "jdbc:mysql:///test?propertiesTransform="+
- "com.mysql.management.jmx.ConnectorMXJPropertiesTransform"; String
- user = "root"; String password = ""; Class.forName(driver); Connection
- conn = DriverManager.getConnection(url, user, password);
-
- You may wish to create a separate users and database table spaces for each
- application, rather than using "root and test".
-
- We highly suggest having a routine backup procedure for backing up the
- database files in the datadir.
Modified: trunk/connector-mxj/index.html
===================================================================
--- trunk/connector-mxj/index.html 2007-06-30 09:43:15 UTC (rev 102)
+++ trunk/connector-mxj/index.html 2007-07-09 07:52:26 UTC (rev 103)
@@ -1,576 +1,12 @@
-<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.
- MySQL Connector/MXJ
- </title><meta content="DocBook XSL Stylesheets V1.67.2" name="generator"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mysql-install-wizard"></a>1.
- MySQL Connector/MXJ
- </h2></div></div><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-introduction"></a>1.1.
- Introduction
- </h3></div></div></div><p class="remark"><i><span class="remark">
- [EH] Some of the steps
- documented are very basic (like requiring a JDK); feel free to skip
- over the obvious ones, and please understand that I've tried to be
- complete, I'm not trying to talk down to the audience. -- Eric Herman
- 2004 Aug 20
- </span></i></p><p>
- MySQL Connector/MXJ is a Java Utility package for deploying and managing a
- MySQL database. Connector/MXJ may be bundled in to an existing Java
- application or may be deployed as a JMX MBean. Deploying and using MySQL
- can be as easy as adding an additional parameter to the JDBC connection
- url, which will result in the database being started when the first
- connection is made.
- This makes it easy for Java developers to deploy applications which
- require a database by reducing installation barriers for their
- end-users.
- </p><p>
- MySQL Connector/MXJ makes the MySQL database appear to be a
- java-based component. It does this by determining what platform the
- system is running on, selecting the appropriate binary, and launching
- the executable. It will also optionally deploy an initial database, with
- any specified parameters.
- </p><p>
- As a JMX MBean, MySQL Connector/MXJ requires a JMX v1.2 compliant MBean
- container, such as JBoss version 4. The MBean will uses the standard JMX
- management APIs to present (and allow the setting of) parameters which are
- appropriate for that platform.
- </p><p>
- Included are instructions for use with a JDBC driver and deploying as a JMX
- MBean to JBoss.
- </p><p>
- You can download sources and binaries from:
- <a href="http://dev.mysql.com/downloads/connector/mxj/" target="_top">
- http://dev.mysql.com/downloads/connector/mxj/
- </a>
- </p><p>
- This an beta release and feedback is welcome and encouraged.
- </p><p>
- Please send questions or comments to
- <a href="mailto:java@stripped" target="_top">java@stripped</a>.
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-supported"></a>1.2.
- Support Platforms:
- </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
- Linux, i386
- </p></li><li><p>
- Windows NT, x86
- </p></li><li><p>
- Windows 2000, x86
- </p></li><li><p>
- Windows XP, x86
- </p></li><li><p>
- Solaris 9, SPARC 32
- </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-test-requirements"></a>1.3.
- JUnit Test Requirements
- </h3></div></div></div><p>
- The best way to ensure that your platform is supported is to run
- the JUnit tests.
- </p><p>
- The first thing to do is make sure that the components will work on
- the platform. Since the ''MysqldResource'' class is really a wrapper for a
- native version of MySQL, not all platforms are supported. At the time
- of this writing, Linux on the i386 architecture has been tested and
- seems to work quite well, as does OS X v10.3. There has been limited
- testing on Windows and Solaris.
- </p><p>
- Requirements:
- </p><div class="orderedlist"><ol type="1"><li><p>
- JDK-1.4 or newer (or the JRE if you aren't going to be compiling the
- source or JSPs).
- </p></li><li><p>
- MySQL Connector/J version 3.1 or newer (from
- <a href="http://dev.mysql.com/downloads/connector/j/" target="_top">
- http://dev.mysql.com/downloads/connector/j/
- </a>)
- installed and available via your CLASSPATH.
- </p></li><li><p>
- The <code class="literal">javax.management</code> classes for JMX version
- 1.2.1, these are present in the following application servers:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- JBoss - 4.0rc1 or newer
- </p></li><li><p>
- Apache Tomcat - 5.0 or newer
- </p></li><li><p>
- Sun's JMX reference implementation version 1.2.1
- <a href="http://java.sun.com/products/JavaManagement/" target="_top">
- http://java.sun.com/products/JavaManagement/</a>
- </p></li></ul></div></li><li><p>
- Junit 3.8.1 (from
- <a href="http://www.junit.org/" target="_top">http://www.junit.org/</a>)
- </p></li></ol></div><p>
- If building from source, All of the requirements from above, plus:
- </p><div class="orderedlist"><ol type="1"><li><p>
- Ant version 1.5 or newer (download from
- <a href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>)
- </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-testing-"></a>1.4.
- Running the JUnit Tests
- </h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>
- The tests attempt to launch MySQL on the port 3336. If you have a MySQL
- running, it may conflict, but this isn't very likely since thedefault port
- for MySQL is 3306. However, You may set the "c-mxj_test_port" Java property
- to a port of your choosing. Alternatively, you may wish to start by
- shutting down any instances of MySQL you have running on the target machine.
- </p><p>
- The tests surpress output to the console by default. For verbose output, you
- may set the "c-mxj_test_silent" Java property to "false".
- </p></li><li><p>
- In order to run the JUnit test suite, the $CLASSPATH must include
- the following:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- JUnit
- </p></li><li><p>
- JMX
- </p></li><li><p>
- Connector/J
- </p></li><li><p>
- MySQL Connector/MXJ
- </p></li></ul></div></li><li><p>
- If <code class="filename">connector-mxj.jar</code> is not present in your
- download, unzip MySQL Connector/MXJ source archive.
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>MySQL Connector/MXJ</title>
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+ <p><a href="http://dev.mysql.com/doc/refman/5.0/en/connector-mxj.html">
+ Documentation</a>
+ </p>
+</body>
+</html>
-<pre class="programlisting">
-cd mysqldjmx
-ant dist
- </pre>
-
- Then add
- <code class="filename">$TEMP/cmxj/stage/connector-mxj/connector-mxj.jar</code>
- to the CLASSPATH.
- </p></li><li><p>
- if you have <code class="literal">junit</code>, execute the unit tests. From
- the command line, type:
-
-<pre class="programlisting">
-java junit.textui.TestRunner com.mysql.management.AllTestsSuite
- </pre>
-
- The output should look something like this:
-
-<pre class="programlisting">
-.........................................
-.........................................
-..........
-Time: 259.438
-
-OK (101 tests)
- </pre>
-
- Note that the tests are a bit slow near the end, so please be
- patient.
- </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-driver-launched"></a>1.5.
- Running as part of the JDBC Driver
- </h3></div></div></div><p>
- A feature of the MySQL Connector/J JDBC driver is the ability to specify a
- ''SocketFactory'' as a parameter in the JDBC connection string. MySQL Connector/MXJ
- includes a custom SocketFactory. The SocketFactory will, upon the first
- connection, deploy and launch the MySQL database.
- The SocketFactory also exposes a ''shutdown'' method.
- </p><p>
- To try it specify the ''socketFactory'' parameter on the JDBC connection
- string with a value equal to
- ''com.mysql.management.driverlaunched.ServerLauncherSocketFactory''
- </p><p>
- In the following example, we have a program which creates a connection, executes
- a query, and prints the result to the System.out. The MySQL database will be
- deployed and started as part of the connection process, and shutdown as part of
- the finally block.
- </p><pre class="programlisting">
-import java.sql.Connection;
-import java.sql.DriverManager;
-import java.sql.ResultSet;
-import java.sql.Statement;
-
-import com.mysql.management.driverlaunched.ServerLauncherSocketFactory;
-
-public class ConnectorMXJTestExample {
- public static void main(String[] args) throws Exception {
- String hostColonPort = "localhost:3336";
-
- String driver = com.mysql.jdbc.Driver.class.getName();
- String url = "jdbc:mysql://" + hostColonPort + "/" + "?"
- + "socketFactory="
- + ServerLauncherSocketFactory.class.getName();
- String userName = "root";
- String password = "";
-
- Class.forName(driver);
- Connection conn = null;
- try {
- conn = DriverManager.getConnection(url, userName, password);
- Statement stmt = conn.createStatement();
- ResultSet rs = stmt.executeQuery("SELECT VERSION()");
- rs.next();
- String version = rs.getString(1);
- rs.close();
- stmt.close();
-
- System.out.println("------------------------");
- System.out.println(version);
- System.out.println("------------------------");
- } finally {
- try {
- conn.close();
- } catch (Exception e) {
- e.printStackTrace();
- }
- ServerLauncherSocketFactory.shutdown(hostColonPort);
- }
- }
-}
- </pre><p>
- To run the above program, be sure to have connector-mxj.jar and Connector/J in
- the CLASSPATH. Then type:
- </p><pre class="programlisting">
-java ConnectorMXJTestExample
- </pre><p>
- Of course there are many options we may wish to set for a MySQL database.
- These options may be specified as part of the JDBC connection string simply
- by prefixing each server option with ''server.''. In the following example
- we set three driver parameters and two server parameters:
- </p><pre class="programlisting">
- String url = "jdbc:mysql://" + hostColonPort + "/"
- + "?"
- + "socketFactory="
- + ServerLauncherSocketFactory.class.getName();
- + "&"
- + "cacheServerConfiguration=true"
- + "&"
- + "useLocalSessionState=true"
- + "&"
- + "server.basedir=/opt/myapp/db"
- + "&"
- + "server.datadir=/mnt/bigdisk/myapp/data";
- </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-java-object"></a>1.6.
- Running within a Java Object
- </h3></div></div></div><p>
- Have a java application and wish to "embed" a MySQL database, make use of the
- com.mysql.management.MysqldResource class directly. This class may be
- instantiated with the default (no argument) constructor, or by passing in a
- java.io.File object representing the directory you wish the server to be
- "unzipped" into. It may also be instantiated with printstreams for "stdout"
- and "stderr" for logging.
- </p><p>
- Once instantiated, a java.util.Map, the object will be able to provide a
- java.util.Map of server options appropriate for the platform and version of
- MySQL which you will be using.
- </p><p>
- The MysqldResource will allow you to "start" MySQL with a java.util.Map of
- server options which you provide, as well as "shutdown" the database.
-
- The following example shows a simplistic way to embed MySQL in an applicaiton
- using plain java objects:
- </p><pre class="programlisting">
-import com.mysql.management.MysqldResource;
-
- ...
-
- public void startMySQL() {
- File baseDir = new File(ourAppDir, "mysql");
- mysqldResource = new MysqldResource(baseDir);
- Map options = new HashMap();
- options.put("port", "3336");
- String threadName = "OurApp MySQL";
- mysqldResource.start(threadName, options);
- }
-
- public void stopMySQL() {
- if (mysqldResource != null) {
- mysqldResource.shutdown();
- }
- mysqldResource = null;
- }
-
- public java.sql.Connection getConnection() throws Exception {
- String db = "test";
- String url = "jdbc:mysql://localhost:3336/" + db;
- String userName = "root";
- String password = "";
- Class.forName(com.mysql.jdbc.Driver.class.getName());
- return DriverManager.getConnection(url, userName, password);
- }
- </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-java-api"></a>1.7.
- The MysqldResource API
- </h3></div></div></div><p>
- Constructors:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- public MysqldResource(File baseDir, PrintStream out, PrintStream err);
- </p><p>
- Allows the setting of the "basedir" to deploy the MySQL files to, as well
- as out put streams for standard out and standard err.
- </p></li><li><p>
- public MysqldResource(File baseDir);
- </p><p>
- Allows the setting of the "basedir" to deploy the MySQL files to. Output
- for standard out and standard err are directed to System.out and
- System.err.
- </p></li><li><p>
- public MysqldResource();
- </p><p>
- The basedir is defaulted to a subdirectory of the java.io.tempdir.
- Output for standard out and standard err are directed to System.out and
- System.err;
- </p></li></ul></div><p>
- MysqldResource API includes the following methods:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- void start(String threadName, Map mysqldArgs);
- </p><p>
- Deploys and starts MySQL. The "threadName" string is used to name the thread
- which actually performs the execution of the MySQL command line. The map is
- the set of arguments and their values to be passed to the command line.
- </p></li><li><p>
- void shutdown();
- </p><p>
- Shuts down the MySQL instance managed by the MysqldResource object.
- </p></li><li><p>
- Map getServerOptions();
- </p><p>
- Returns a map of all the options and their current (or default, if not
- running)
- options available for the MySQL database.
- </p></li><li><p>
- boolean isRunning();
- </p><p>
- Returns true if the MySQL database is running.
- </p></li><li><p>
- boolean isReadyForConnections();
- </p><p>
- Returns true once the database reports that is is ready for connections.
- </p></li><li><p>
- void setKillDelay(int millis);
- </p><p>
- The default "Kill Delay" is 30 seconds. This represents the amount of time
- to wait between the initial request to shutdown and issuing a "force kill"
- if the database has not shutdown by itself.
- </p></li><li><p>
- void addCompletionListenser(Runnable listener);
- </p><p>
- Allows for applications to be notified when the server process completes.
- Each ''listener'' will be fired off in its own thread.
- </p></li><li><p>
- String getVersion();
- </p><p>
- returns the version of MySQL.
- </p></li><li><p>
- void setVersion(int MajorVersion, int minorVersion, int patchLevel);
- </p><p>
- The standard distribution comes with only one version of MySQL packaged.
- However, it is possible to package multiple versions, and specify which
- version to use.
- </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-jmx-agent"></a>1.8.
- Running within a JMX Agent (custom)
- </h3></div></div></div><p>
- If you are not using the SUN Reference implementation of the JMX
- libraries, you should skip this section. Or, if you are deploying to JBoss,
- you also may wish to skip to the next section.
- </p><p>
- We want to see the MysqldDynamicMBean in action inside of a JMX
- agent. In the <code class="literal">com.mysql.management.jmx.sunri</code> package
- is a custom JMX agent with two MBeans:
-
- <div class="orderedlist"><ol type="1"><li><p>
- the MysqldDynamicMBean, and
- </p></li><li><p>
- a com.sun.jdmk.comm.HtmlAdaptorServer, which provides a web
- interface for manipulating the beans inside of a JMX agent.
- </p></li></ol></div>
-
- When this very simple agent is started, it will allow a MySQL
- database to be started and stopped with a web browser.
- </p><div class="orderedlist"><ol type="1"><li><p>
- Complete the testing of the platform as above.
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- current JDK, JUnit, Connector/J, MySQL Connector/MXJ
- </p></li><li><p>
- this section <span class="emphasis"><em>requires</em></span> the SUN reference
- implementation of JMX
- </p></li><li><p>
- PATH, JAVA_HOME, ANT_HOME, CLASSPATH
- </p></li></ul></div></li><li><p>
- If not building from source, skip to next step
- </p><p>
- rebuild with the "sunri.present"
- </p><pre class="programlisting">
-ant -Dsunri.present=true dist
-re-run tests:
-java junit.textui.TestRunner com.mysql.management.AllTestsSuite
- </pre></li><li><p>
- launch the test agent from the command line:
-
-<pre class="programlisting">
-java com.mysql.management.jmx.sunri.MysqldTestAgentSunHtmlAdaptor &
- </pre>
- </p></li><li><p>
- from a browser:
-
-<pre class="programlisting">
-http://localhost:9092/
- </pre>
- </p></li><li><p>
- under MysqldAgent,
-
-<pre class="programlisting">
-select "name=mysqld"
- </pre>
- </p></li><li><p>
- Observe the MBean View
- </p></li><li><p>
- scroll to the bottom of the screen press the
- <span class="guibutton">startMysqld</span> button
- </p></li><li><p>
- click <code class="literal">Back to MBean View</code>
- </p></li><li><p>
- scroll to the bottom of the screen press
- <span class="guibutton">stopMysqld</span> button
- </p></li><li><p>
- kill the java process running the Test Agent (jmx server)
- </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-standard-environment"></a>1.9.
- Deployment in a standard JMX Agent environment (JBoss)
- </h3></div></div></div><p>
- Once there is confidence that the MBean will function on the
- platform, deploying the MBean inside of a standard JMX Agent is the
- next step. Included are instructions for deploying to JBoss.
- </p><div class="orderedlist"><ol type="1"><li><p>
- Ensure a current version of java development kit (v1.4.x), see
- above.
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- Ensure <code class="literal">JAVA_HOME</code> is set (JBoss requires
- <code class="literal">JAVA_HOME</code>)
- </p></li><li><p>
- Ensure <code class="literal">JAVA_HOME/bin</code> is in the
- <code class="literal">PATH</code> (You will NOT need to set your CLASSPATH,
- nor will you need any of the jars used in the previous tests).
- </p></li></ul></div></li><li><p>
- Ensure a current version of JBoss (v4.0RC1 or better)
-
-<pre class="programlisting">
-http://www.jboss.org/index.html
-select "Downloads"
-select "jboss-4.0.zip"
-pick a mirror
-unzip ~/dload/jboss-4.0.zip
-create a JBOSS_HOME environment variable set to the unzipped directory
-unix only:
-cd $JBOSS_HOME/bin
-chmod +x *.sh
- </pre>
- </p></li><li><p>
- Deploy (copy) the <code class="filename">connector-mxj.jar</code> to
- <code class="filename">$JBOSS_HOME/server/default/lib</code>.
- </p></li><li><p>
- Deploy (copy)
- <code class="filename">mysql-connector-java-3.1.4-beta-bin.jar</code> to
- <code class="filename">$JBOSS_HOME/server/default/lib</code>.
- </p></li><li><p>
- Create a <code class="filename">mxjtest.war</code> directory in
- <code class="filename">$JBOSS_HOME/server/default/deploy</code>.
- </p></li><li><p>
- Deploy (copy) <code class="filename">index.jsp</code> to
- <code class="filename">$JBOSS_HOME/server/default/deploy/mxjtest.war</code>.
- </p></li><li><p>
- Create a <code class="filename">mysqld-service.xml</code> file in
- <code class="filename">$JBOSS_HOME/server/default/deploy</code>.
-
-<pre class="programlisting">
-<?xml version="1.0" encoding="UTF-8"?>
- <server>
- <mbean code="com.mysql.management.jmx.jboss.JBossMysqldDynamicMBean"
- name="mysql:type=service,name=mysqld">
- <attribute name="datadir">/tmp/xxx_data_xxx</attribute>
- <attribute name="autostart">true</attribute>
- </mbean>
- </server>
- </pre>
- </p></li><li><p>
- Start jboss:
-
- <div class="itemizedlist"><ul type="disc"><li><p>
- on unix: <span><strong class="command">$JBOSS_HOME/bin/run.sh</strong></span>
- </p></li><li><p>
- on windows: <span><strong class="command">%JBOSS_HOME%\bin\run.bat</strong></span>
- </p></li></ul></div>
- </p><p>
- Be ready: JBoss sends a lot of output to the screen.
- </p></li><li><p>
- When JBoss seems to have stopped sending output to the screen, open
- a web browser to:
- <code class="literal">http://localhost:8080/jmx-console</code>
- </p></li><li><p>
- Scroll down to the bottom of the page in the
- <code class="literal">mysql</code> section, select the bulleted
- <code class="literal">mysqld</code> link.
- </p></li><li><p>
- Observe the JMX MBean View page. MySQL should already be running.
- </p></li><li><p>
- (If "autostart=true" was set, you may skip this step.) Scroll to the
- bottom of the screen. You may press the
- <span class="guibutton">Invoke</span> button to stop (or start) MySQL
- observe <code class="literal">Operation completed successfully without a return
- value.</code> Click <code class="literal">Back to MBean View</code>
- </p></li><li><p>
- To confirm MySQL is running, open a web browser to
- <code class="literal">http://localhost:8080/mxjtest/</code> and you should see
- that
-
-<pre class="programlisting">SELECT 1</pre>
-
- returned with a result of
-
-<pre class="programlisting">1</pre>
- </p></li><li><p>
- Guided by the
- <code class="filename">$JBOSS_HOME/server/default/deploy/mxjtest.war/index.jsp</code>
- you will be able to use MySQL in your Web Application. There is a
- <code class="literal">test</code> database and a <code class="literal">root</code> user
- (no password) ready to expirement with. Try creating a table,
- inserting some rows, and doing some selects.
- </p></li><li><p>
- Shut down MySQL. MySQL will be stopped automatically when JBoss is
- stopped, or: from the browser, scroll down to the bottom of the
- MBean View press the stop service <span class="guibutton">Invoke</span>
- button to halt the service. Observe <code class="literal">Operation completed
- successfully without a return value.</code> Using
- <code class="literal">ps</code> or <code class="literal">task manager</code> see that
- MySQL is no longer running
- </p></li></ol></div><p>
- As of 1.0.6-beta version is the ability to have the MBean start
- the MySQL database upon start up. Also, we've taken advantage of the JBoss
- life-cycle extension methods so that the database will gracefully shut down when
- JBoss is shutdown.
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mxj-install"></a>1.10.
- Installation
- </h3></div></div></div><p>
- If you've worked through the above sections, you've arleady performed
- these steps. But we list them here for quick reference.
- </p><p>
- Driver Launched:
- </p><div class="orderedlist"><ol type="1"><li><p>
- Download and unzip Connector/MXJ, add connector-mxj.jar to the CLASSPATH
- </p></li><li><p>
- To the JDBC connection string add the following parameter:
- "socketFactory=" + ServerLauncherSocketFactory.class.getName()
- </p></li></ol></div><p>
- JBoss:
- </p><div class="orderedlist"><ol type="1"><li><p>
- Download Connector/MXJ copy the
- <code class="filename">connector-mxj.jar</code> file to the
- <code class="filename">$JBOSS_HOME/server/default/lib</code> diretory.
- </p></li><li><p>
- Download Connector/J copy the <code class="filename">connector-mxj.jar</code>
- file to the <code class="filename">$JBOSS_HOME/server/default/lib</code>
- diretory.
- </p></li><li><p>
- Create an MBean service xml file in the
- <code class="filename">$JBOSS_HOME/server/default/deploy</code> directory
- with any attributes set, for instance the <code class="literal">datadir</code>
- and <code class="literal">autostart</code>.
- </p></li><li><p>
- Set the JDBC parameters of your web application to use: <code class="literal">
- String driver = "com.mysql.jdbc.Driver"; String url =
- "jdbc:mysql:///test?propertiesTransform="+
- "com.mysql.management.jmx.ConnectorMXJPropertiesTransform";
- String user = "root"; String password = ""; Class.forName(driver);
- Connection conn = DriverManager.getConnection(url, user, password);
- </code>
- </p></li></ol></div><p>
- You may wish to create a separate users and database table spaces for
- each application, rather than using "root and test".
- </p><p>
- We highly suggest having a routine backup procedure for backing up
- the database files in the <code class="literal">datadir</code>.
- </p></div></div></body></html>
\ No newline at end of file
Modified: trunk/connector-mxj/src/com/mysql/management/driverlaunched/ServerLauncherSocketFactory.java
===================================================================
--- trunk/connector-mxj/src/com/mysql/management/driverlaunched/ServerLauncherSocketFactory.java 2007-06-30 09:43:15 UTC (rev 102)
+++ trunk/connector-mxj/src/com/mysql/management/driverlaunched/ServerLauncherSocketFactory.java 2007-07-09 07:52:26 UTC (rev 103)
@@ -125,7 +125,9 @@
}.exec();
runningPort = mysqld.getPort();
}
- if (port != runningPort) {
+ if (runningPort <= 0) {
+ System.err.println("unable to confirm running port of " + port);
+ } else if (port != runningPort) {
String location = mysqld.getBaseDir().getPath();
if (dataDir != null) {
location += " with data at " + dataDir;
| Thread |
|---|
| • Connector/MXJ commit: r103 - in trunk/connector-mxj: . src/com/mysql/management/driverlaunched | eherman | 9 Jul |
