db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject svn commit: r355248 [3/3] - in /db/derby/site/trunk: build/site/ build/site/papers/ build/site/papers/DerbyTut/ build/site/skin/ src/documentation/ src/documentation/content/xdocs/ src/documentation/content/xdocs/papers/ src/documentation/content/xdocs...
Date Thu, 08 Dec 2005 22:30:16 GMT
Added: db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyTut/ns_intro.xml
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyTut/ns_intro.xml?rev=355248&view=auto
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyTut/ns_intro.xml (added)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyTut/ns_intro.xml Thu Dec
 8 14:30:05 2005
@@ -0,0 +1,479 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document> 
+
+<header> <title>Step 4: Derby Network Server</title> </header> 
+
+<body> 
+
+<section id="ns_intro">
+<title>Introduction</title>
+<p>
+The "<a href="embedded_intro.html">Embedded Derby</a>" section
+shows how two applications running in different JVMs,
+<code>ij</code> and <code>SimpleApp</code>,
+can't use the Derby Embedded JDBC driver to connect
+to the same <code>derbyDB</code> database simultaneously
+because only one JVM can access a given database.
+</p>
+
+<p>
+The solution is to introduce a framework that embeds Derby and handles
+database requests from multiple applications.
+The Derby Network Server is such a framework. It is a embedded Derby 
+application that manages requests from network clients,
+as depicted in Figure 2.
+</p>
+
+<p>
+<strong>Figure 2: Derby Network Server Architecture</strong>
+</p>
+<p>
+<img src="network_server.png" alt="Figure 2: Derby Network Server Architecture" />
+</p>
+
+<p>
+This section shows how to start the Derby Network Server,
+configure your environment to use the Derby Network Client JDBC driver,
+and compile and run a simple Java application that uses the network server.
+The information presented here is minimal, just enough to help get new 
+users started.
+For complete information, see part one of the
+<a href="http://db.apache.org/derby/manuals">Derby Server and 
+Administration Guide</a>.
+</p>
+</section>
+
+<section id="ns">
+<title>Derby Network Server</title>
+
+<p>
+   First set the
+   <a href="install_software.html#set_derby_install">DERBY_INSTALL</a>
+   environment variable.
+</p>
+
+   <section id="ns_config_env">
+   <title>Configure environment</title>
+   <p>To start or stop the Network Server,
+      set your <code>CLASSPATH</code> to include the jar files listed below:</p>
+  
+   <ul>
+     <li> <code>derby.jar</code>: contains the Derby engine </li>
+     <li> <code>derbynet.jar</code>: contains the code for
+   the Derby Network Server
+     </li>
+</ul>
+
+<p>
+   You can set your <code>CLASSPATH</code> explicitly with the command
+   shown below:
+</p>
+<p class="code-block">Windows:
+C:\&gt; set CLASSPATH=%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbytools.jar;%DERBY_INSTALL%\lib\derbynet.jar;.
+</p>
+
+<p class="code-block">UNIX:
+$ export CLASSPATH=$DERBY_INSTALL/lib/derby.jar:$DERBY_INSTALL/lib/derbytools.jar:$DERBY_INSTALL\lib\derbynet.jar:.
+</p>
+<p>
+   You can also use the script that the Derby software distribution provides 
+   to set <code>CLASSPATH</code>.
+   Change directory to the
+   <code>DERBY_INSTALL/frameworks/NetworkServer/bin</code> directory,
+    then execute
+   <code>setNetworkServerCP.bat</code> (Windows) or
+     <code>setNetworkServerCP.ksh</code> (UNIX), as shown below:
+   </p>
+
+<p class="code-block">Windows:
+C:\&gt; cd %DERBY_INSTALL%\frameworks\NetworkServer\bin
+C:\Apache\db-derby-10.1.2.1-bin\frameworks\NetworkServer\bin&gt; setNetworkServerCP.bat
+</p>
+
+<p class="code-block">UNIX:
+$ cd $DERBY_INSTALL/frameworks/NetworkServer/bin
+$ . setNetworkServerCP.ksh
+</p>
+
+</section>
+<section id="start_ns">
+<title>Start Network Server</title>
+
+<p>
+Start the Network server by executing the
+<code>startNetworkServer.bat</code> (Windows) or
+<code>startNetworkServer.ksh</code> (UNIX) script.
+This will start the Network Server up on port 1527 and echo a startup
+message:
+</p>
+
+<p class="code-block">Windows:
+C:\Apache\db-derby-10.1.2.1-bin\frameworks\NetworkServer\bin&gt; startNetworkServer.bat
+Server is ready to accept connections on port 1527.
+</p>
+<p class="code-block">UNIX:
+$ startNetworkServer.ksh
+Server is ready to accept connections on port 1527.
+</p>
+
+<p>
+Messages will continue to be output to this window as the Network Server
+processes connection requests.
+</p>
+
+<p>
+The Network Server starts Derby, so you'll find the <code>derby.log</code>
+error log in the directory where you start the Network Server.
+</p>
+
+</section>
+
+</section>
+
+<section id="ns_sample">
+<title>Sample Application</title>
+
+<p>
+   Open a new window and set the
+   <a href="install_software.html#set_derby_install">DERBY_INSTALL</a>
+   environment variable.
+</p>
+
+   <section id="configure_ns_client">
+   <title>Configure environment to use Derby Network Client JDBC driver</title>
+
+   <p>To use the Derby Network Client JDBC driver,
+      set your <code>CLASSPATH</code> to include the jar files listed below:</p>
+   <ul>
+     <li> <code>derbyclient.jar</code>: contains the JDBC driver
+     </li>
+     <li> <code>derbytools.jar</code>:
+           optional, provides the <code>ij</code> tool</li>
+</ul>
+
+<p>
+   You can set your <code>CLASSPATH</code> explicitly with the command
+   shown below:
+</p>
+<p class="code-block">Windows:
+C:\&gt; set CLASSPATH=%DERBY_INSTALL%\lib\derbyclient.jar;%DERBY_INSTALL%\lib\derbytools.jar;.
+</p>
+
+<p class="code-block">UNIX:
+$ export CLASSPATH=$DERBY_INSTALL/lib/derbyclient.jar:$DERBY_INSTALL/lib/derbytools.jar:.
+</p>
+<p>
+   You can also use the script that the Derby software distribution provides 
+   to set <code>CLASSPATH</code>.
+   Change directory to the
+   <code>DERBY_INSTALL/frameworks/NetworkServer/bin</code> directory,
+    then execute
+    the <code>setNetworkClientCP.bat</code> (Windows) or
+     <code>setNetworkClientCP.ksh</code> (UNIX) script as shown below:
+    </p>
+
+<p class="code-block">Windows:
+C:\Apache\db-derby-10.1.2.1-bin\frameworks\NetworkServer\bin&gt; setNetworkClientCP.bat
+</p>
+
+<p class="code-block">UNIX:
+$ . setNetworkClientCP.ksh
+</p>
+   </section>
+
+   <section id="ij_ns_client">
+   <title>Test network server connection with ij</title>
+
+   <p>
+   An <strong>embedded</strong> 
+   connection URL that creates and connects to a database
+   looks like this:
+   </p>
+
+   <p class="code-block">java org.apache.derby.tools.ij
+ij&gt; connect 'jdbc:derby:MyDbTest;create=true';</p>
+
+   <p>
+   A Derby Network Client connection URL is very close; just add
+   <code>//localhost:1527/</code> before the database name:
+   </p>
+
+   <p class="code-block">java org.apache.derby.tools.ij
+ij&gt; connect 'jdbc:derby://localhost:1527/MyDbTest;create=true';</p>
+
+   <p>
+   Where is the physical location of the newly created database?
+   </p>
+   <p>
+   If you use the embedded driver, by default the database is created
+   in the same directory in which <code>ij</code> was started up.
+   If you use the Derby Network Client JDBC driver, 
+   by default the database is created
+   in the directory where the Network Server was started up; 
+   in other words, in
+   <code>DERBY_INSTALL/frameworks/NetworkServer/bin</code>.
+   </p>
+
+   <p>
+   Derby provides many ways to specify the actual location.
+   For example, the connection URL below specifies a full path for the database
+   location:
+   </p>
+   <p class="code-block">java org.apache.derby.tools.ij
+ij&gt; connect 'jdbc:derby://localhost:1527//home/bill/DerbyDb/MyDbTest;create=true';</p>
+
+   <p>
+   The <em>Developer's Guide</em> provides information
+   about where Derby looks for databases:
+   </p>
+
+   <ul>
+      <li><a href="http://db.apache.org/derby/docs/dev/devguide/cdevdvlp34964.html">Connecting
to databases</a></li>
+      <li> <a href="http://db.apache.org/derby/docs/dev/devguide/cdevdvlp13018.html">Defining
the system directory</a></li>
+   </ul>
+
+   </section>
+
+   <section id="copy_ns_client">
+   <title>Copy sample application</title>
+
+   <p>
+   This section uses the same sample application that the 
+   "<a href="embedded_intro.html">Embedded Derby</a>" section uses.
+   Copy that application
+   into your current directory as shown below:
+   </p>
+
+<p class="code-block">Windows:
+c:\&gt; copy %DERBY_INSTALL%\demo\simple\SimpleApp.java .
+</p>
+
+<p class="code-block">UNIX:
+cp $DERBY_INSTALL/demo/simple/SimpleApp.java .
+</p>
+
+   <p>
+   By default this application runs in embedded mode.
+   If you pass it the <code>derbyclient</code> argument at run time, 
+   then it will
+   create and connect to the database using the Derby Network Client JDBC
+   driver instead.
+   </p>
+
+   </section>
+
+   <section id="ns_lookat_code">
+   <title>A quick look at the code</title>
+
+   <p>
+   The <code>SimpleApp.java</code> application spends most of its time
+   creating a table, inserting data into that table, and selecting the
+   data back, demonstrating many JDBC calls as it does so.
+   This section highlights the JDBC calls that make this specifically a
+   client/server Derby application.
+   The "<a href="embedded_intro.html#em_lookat_code">Embedded Derby</a>"
+   section shows how to turn the same code into an embedded application.
+   </p>
+
+   <section id="jdbc_ns_client">
+   <title>Load the Client JDBC Driver</title>
+   <p>
+   When executed with the <code>derbyclient</code> argument,
+   the <code>SimpleApp</code> application
+   loads the Derby Network Client driver with this code:
+   </p>
+
+<p class="code-block">driver = "org.apache.derby.jdbc.ClientDriver";
+...
+Class.forName(driver).newInstance();
+</p>
+   </section>
+
+   <section id="url_ns_client">
+   <title>Get a Network Server Connection</title>
+   <p>
+   When executed with the <code>derbyclient</code> argument,
+   the <code>SimpleApp</code> application
+   creates and connects to the <code>derbyDB</code> database with this code:
+   </p>
+
+<p class="code-block">protocol = "jdbc:derby://localhost:1527/";
+...
+conn = DriverManager.getConnection(protocol + "derbyDB;create=true", props);
+</p>
+   <p>
+   That connection URL, fully constructed, looks like this:
+   </p>
+
+   <p class="code-block">jdbc:derby://localhost:1527/derbyDB;create=true</p>
+   </section>
+
+   <section id="ns_client_noshutdown">
+   <title>Don't shut Derby down</title>
+
+   <p>
+   If you look at the <code>SimpleApp.java</code> code you'll notice that it
+   only shuts Derby down if it's running in embedded mode.
+   When connecting <em>via</em> the Network Server, 
+   other applications might be accessing
+   the same database you are; so, don't shut down the databases or Derby.
+   </p>
+
+   </section>
+   </section>
+
+   <section id="compile_ns_client">
+   <title>Compile Sample Application</title>
+   <p>
+   Compile the sample application as shown below:
+   </p>
+   
+   <p class="code-block">javac SimpleApp.java</p>
+   </section>
+
+   <section id="run_ns_client">
+   <title>Run Sample Application</title>
+   <p>
+   Run the sample application like this:
+   </p>
+
+   <p class="code-block">java SimpleApp derbyclient</p>
+
+   <p>You should see the output shown below:</p>
+
+   <p class="code-block">SimpleApp starting in derbyclient mode.
+Loaded the appropriate driver.
+Connected to and created database derbyDB
+Created table derbyDB
+Inserted 1956 Webster
+Inserted 1910 Union
+Updated 1956 Webster to 180 Grand
+Updated 180 Grand to 300 Lakeshore
+Verified the rows
+Dropped table derbyDB
+Closed result set and statement
+Committed transaction and closed connection
+SimpleApp finished</p>
+
+   <p>Quick question: 
+      Where is the physical location of the <code>derbyDB</code> database 
+      that the sample application creates?
+   </p>
+
+   <p><em>(Answer: In the default
+   <code>$DERBY_INSTALL/frameworks/NetworkServer/bin</code> location.)
+   </em>
+   </p>
+
+   </section>
+
+</section>
+
+<section id="stop_ns">
+<title>Stop Network Server</title>
+<p>
+Stop the Network server by executing the
+<code>stopNetworkServer.bat</code> (Windows) or
+<code>stopNetworkServer.ksh</code> (UNIX) script, as shown below:
+</p>
+
+<p class="code-block">Windows:
+C:\&gt; cd %DERBY_INSTALL%\frameworks\NetworkServer\bin
+C:\Apache\db-derby-10.1.2.1-bin\frameworks\NetworkServer\bin&gt; setNetworkServerCP.bat
+C:\Apache\db-derby-10.1.2.1-bin\frameworks\NetworkServer\bin&gt; stopNetworkServer.bat
+</p>
+<p class="code-block">UNIX:
+$ cd $DERBY_INSTALL/frameworks/NetworkServer/bin
+$ . setNetworkServerCP.ksh
+$ stopNetworkServer.ksh
+</p>
+<p>The window running the NetworkServer should output a
+'<code>Shutdown successful</code>' message.
+</p>
+</section>
+
+<section id="ns_next_steps">
+<title>Next Steps</title>
+
+<section>
+<title>Network Server Options</title>
+<p>
+By default, the Derby Network Server only accepts requests from the
+localhost on port 1527.
+You can modify the Network Server to:
+</p>
+
+<ul>
+  <li>Listen on a different port.</li>
+  <li>Accept requests from outside the localhost.</li>
+  <li>Run in the Java 2 Security Manager for increased security, 
+      which we strongly recommend.</li>
+</ul>
+
+<p>
+For more information about these options, and more, see the
+<a href="http://db.apache.org/derby/manuals">Derby Server and 
+Administration Guide</a>.
+</p>
+</section>
+
+<section>
+<title>Embedded Server</title>
+<p>
+Up until this point,
+this section has focused on how to start and stop
+the Network Server as an independent process.
+</p>
+<p>
+Another option, called the "embedded server",
+allows an application to load the embedded JDBC driver for its own use and
+start the Network Server to allow remote access by applications running
+in other JVMs.
+The application that does this can access the database with either the
+embedded driver or the client driver.
+</p>
+<p>
+Figure 3 depicts an application called
+<code>MyEmbedSrvApp</code> that loads the embedded driver and also
+starts up the Network Server.
+This allows other applications,
+such as <code>ij</code> and <code>sysinfo</code>,
+to connect to the same database <em>via</em> a client JDBC driver.
+</p>
+
+<p>
+<strong>Figure 3: Derby Embedded Server Architecture</strong>
+</p>
+<p>
+<img src="embedded_server.png" alt="Figure 3: Derby Embedded Server Architecture" />
+</p>
+
+<p>
+While it is certainly <em>possible</em> 
+for <code>MyEmbedSrvApp</code> 
+to use the Derby Network Client JDBC driver, 
+it's probably better for it to use the embedded driver
+because Derby Network Client JDBC database requests will incur the
+overhead of going out through the network.
+The embedded server architecture lets
+the application that embeds Derby retain the advantages of
+embedded access while
+also enabling remote access to the same database using another tool,
+such as <code>ij</code> or <code>sysinfo</code>.
+So, you end up with the best of both worlds: embedded and client/server.
+</p>
+</section>
+
+<p>
+You've reached the end of this Derby tutorial and should now understand
+how to use Derby in the embedded and Network Server frameworks.
+The "<a href="index.html#next">Overview</a>" section provides suggestions
+for how you might use Derby with some other products.
+</p>
+
+</section>
+
+
+</body>
+</document>

Propchange: db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyTut/ns_intro.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml?rev=355248&r1=355247&r2=355248&view=diff
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml Thu Dec  8 14:30:05
2005
@@ -151,10 +151,15 @@
   <title>Instruction</title>
 
 <p>
-The information in this section was moved to the
+Check out the <a href="DerbyTut/index.html">Derby web site tutorial</a>.
+</p>
+
+<p>
+The rest of the information previously in this section was moved to the
 <a href="http://wiki.apache.org/db-derby/DerbyInstruction">Derby Wiki</a>
 to make it easier for anyone to add new entries.
 </p>
+
 </section>
 
 <section>

Modified: db/derby/site/trunk/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/content/xdocs/site.xml?rev=355248&r1=355247&r2=355248&view=diff
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/site.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/site.xml Thu Dec  8 14:30:05 2005
@@ -25,6 +25,13 @@
        <derby_web label="Derby Web Site" href="derby_web.html"/>
        <howto     label="Instruction" href="http://wiki.apache.org/db-derby/DerbyInstruction"
/>
        <articles label="Articles/Books" href="http://wiki.apache.org/db-derby/DerbyBooksAndArticles"
/>
+       <derbyTut label="Derby Tutorial" href="DerbyTut/">
+           <index    label="Overview"             href="index.html"/>
+           <install  label="Step 1: Install Software"     href="install_software.html"/>
+           <ij_intro label="Step 2: ij Basics"            href="ij_intro.html"/>
+           <embed    label="Step 3: Embedded Derby"       href="embedded_intro.html"/>
+           <ns       label="Step 4: Derby Network Server" href="ns_intro.html"/>
+       </derbyTut>
   </papers>
 
   <engine label="Derby Engine" href="papers/" tab="papers">

Modified: db/derby/site/trunk/src/documentation/skinconf.xml
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/skinconf.xml?rev=355248&r1=355247&r2=355248&view=diff
==============================================================================
--- db/derby/site/trunk/src/documentation/skinconf.xml (original)
+++ db/derby/site/trunk/src/documentation/skinconf.xml Thu Dec  8 14:30:05 2005
@@ -186,6 +186,14 @@
       background-color: #f0f0f0;
       font-family: monospace;
     }
+    p.code-block {
+      margin-left: 2em;
+      padding: .5em;
+      background-color: #f0f0f0;
+      font-family: Monospace, Courier;
+      font-size: smaller;
+      white-space:pre;
+    }
     <!--Example:
         To override the colours of links only in the footer.
     -->



Mime
View raw message