EMMA Coverage Report (generated Wed Jun 28 22:15:27 PDT 2006)
[all classes][org.apache.derby.jdbc]

COVERAGE SUMMARY FOR SOURCE FILE [ClientDataSource.java]

nameclass, %method, %block, %line, %
ClientDataSource.java100% (1/1)100% (3/3)100% (31/31)100% (6/6)

COVERAGE BREAKDOWN BY CLASS AND METHOD

nameclass, %method, %block, %line, %
     
class ClientDataSource100% (1/1)100% (3/3)100% (31/31)100% (6/6)
ClientDataSource (): void 100% (1/1)100% (3/3)100% (2/2)
getConnection (): Connection 100% (1/1)100% (7/7)100% (1/1)
getConnection (String, String): Connection 100% (1/1)100% (21/21)100% (3/3)

1/*
2 
3   Derby - Class org.apache.derby.client.ClientDataSource
4 
5   Copyright (c) 2001, 2005 The Apache Software Foundation or its licensors, where applicable.
6 
7   Licensed under the Apache License, Version 2.0 (the "License");
8   you may not use this file except in compliance with the License.
9   You may obtain a copy of the License at
10 
11      http://www.apache.org/licenses/LICENSE-2.0
12 
13   Unless required by applicable law or agreed to in writing, software
14   distributed under the License is distributed on an "AS IS" BASIS,
15   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   See the License for the specific language governing permissions and
17   limitations under the License.
18 
19*/
20 
21package org.apache.derby.jdbc;
22 
23import java.sql.Connection;
24import java.sql.SQLException;
25import javax.sql.DataSource;
26 
27import org.apache.derby.client.am.LogWriter;
28import org.apache.derby.client.am.SqlException;
29import org.apache.derby.client.net.NetConnection;
30import org.apache.derby.client.net.NetLogWriter;
31 
32/**
33 * ClientDataSource is a simple data source implementation
34 * that can be used for establishing connections in a
35 * non-pooling, non-distributed environment.
36 * The class ClientConnectionPoolDataSource can be used in a connection pooling environment,
37 * and the class ClientXADataSource can be used in a distributed, and pooling
38 * environment. Use these DataSources if your application runs under
39 * JDBC3.0 or JDBC2.0, that is, on the following Java Virtual Machines:
40 * <p/>
41 * <UL>
42 * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
43 * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
44 * </UL>
45 *
46 * <p>The example below registers a DNC data source object with a JNDI naming service.
47 * <pre>
48 * org.apache.derby.client.ClientDataSource dataSource = new org.apache.derby.client.ClientDataSource ();
49 * dataSource.setServerName ("my_derby_database_server");
50 * dataSource.setDatabaseName ("my_derby_database_name");
51 * javax.naming.Context context = new javax.naming.InitialContext();
52 * context.bind ("jdbc/my_datasource_name", dataSource);
53 * </pre>
54 * The first line of code in the example creates a data source object.
55 * The next two lines initialize the data source's
56 * properties. Then a Java object that references the initial JNDI naming
57 * context is created by calling the
58 * InitialContext() constructor, which is provided by JNDI.
59 * System properties (not shown) are used to tell JNDI the
60 * service provider to use. The JNDI name space is hierarchical,
61 * similar to the directory structure of many file
62 * systems. The data source object is bound to a logical JNDI name
63 * by calling Context.bind(). In this case the JNDI name
64 * identifies a subcontext, "jdbc", of the root naming context
65 * and a logical name, "my_datasource_name", within the jdbc
66 * subcontext. This is all of the code required to deploy
67 * a data source object within JNDI. This example is provided
68 * mainly for illustrative purposes. We expect that developers
69 * or system administrators will normally use a GUI tool to
70 * deploy a data source object.
71 * <p/>
72 * Once a data source has been registered with JNDI,
73 * it can then be used by a JDBC application, as is shown in the
74 * following example.
75 * <pre>
76 * javax.naming.Context context = new javax.naming.InitialContext ();
77 * javax.sql.DataSource dataSource = (javax.sql.DataSource) context.lookup ("jdbc/my_datasource_name");
78 * java.sql.Connection connection = dataSource.getConnection ("user", "password");
79 * </pre>
80 * The first line in the example creates a Java object
81 * that references the initial JNDI naming context. Next, the
82 * initial naming context is used to do a lookup operation
83 * using the logical name of the data source. The
84 * Context.lookup() method returns a reference to a Java Object,
85 * which is narrowed to a javax.sql.DataSource object. In
86 * the last line, the DataSource.getConnection() method
87 * is called to produce a database connection.
88 * <p/>
89 * This simple data source subclass of ClientBaseDataSource maintains
90 * it's own private <code>password</code> property.
91 * <p/>
92 * The specified password, along with the user, is validated by DERBY.
93 * This property can be overwritten by specifing
94 * the password parameter on the DataSource.getConnection() method call.
95 * <p/>
96 * This password property is not declared transient, and therefore
97 * may be serialized to a file in clear-text, or stored
98 * to a JNDI server in clear-text when the data source is saved.
99 * Care must taken by the user to prevent security
100 * breaches.
101 * <p/>
102 */
103public class ClientDataSource extends ClientBaseDataSource implements DataSource {
104    private final static long serialVersionUID = 1894299584216955553L;
105    public static final String className__ = "org.apache.derby.jdbc.ClientDataSource";
106 
107    // If a newer version of a serialized object has to be compatible with an older version, it is important that the newer version abides
108    // by the rules for compatible and incompatible changes.
109    //
110    // A compatible change is one that can be made to a new version of the class, which still keeps the stream compatible with older
111    // versions of the class. Examples of compatible changes are:
112    //
113    // Addition of new fields or classes does not affect serialization, as any new data in the stream is simply ignored by older
114    // versions. When the instance of an older version of the class is deserialized, the newly added field will be set to its default
115    // value.
116    // You can field change access modifiers like private, public, protected or package as they are not reflected to the serial
117    // stream.
118    // You can change a transient or static field to a non-transient or non-static field, as it is similar to adding a field.
119    // You can change the access modifiers for constructors and methods of the class. For instance a previously private method
120    // can now be made public, an instance method can be changed to static, etc. The only exception is that you cannot change
121    // the default signatures for readObject() and writeObject() if you are implementing custom serialization. The serialization
122    // process looks at only instance data, and not the methods of a class.
123    //
124    // Changes which would render the stream incompatible are:
125    //
126    // Once a class implements the Serializable interface, you cannot later make it implement the Externalizable interface, since
127    // this will result in the creation of an incompatible stream.
128    // Deleting fields can cause a problem. Now, when the object is serialized, an earlier version of the class would set the old
129    // field to its default value since nothing was available within the stream. Consequently, this default data may lead the newly
130    // created object to assume an invalid state.
131    // Changing a non-static into static or non-transient into transient is not permitted as it is equivalent to deleting fields.
132    // You also cannot change the field types within a class, as this would cause a failure when attempting to read in the original
133    // field into the new field.
134    // You cannot alter the position of the class in the class hierarchy. Since the fully-qualified class name is written as part of
135    // the bytestream, this change will result in the creation of an incompatible stream.
136    // You cannot change the name of the class or the package it belongs to, as that information is written to the stream during
137    // serialization.
138 
139 
140    /**
141     * Creates a simple DERBY data source with default property values for a non-pooling, non-distributed environment.
142     * No particular DatabaseName or other properties are associated with the data source.
143     * <p/>
144     * Every Java Bean should provide a constructor with no arguments since many beanboxes attempt to instantiate a bean
145     * by invoking its no-argument constructor.
146     */
147    public ClientDataSource() {
148        super();
149    }
150 
151 
152    // ---------------------------interface methods-------------------------------
153 
154    /**
155     * Attempt to establish a database connection in a non-pooling, non-distributed environment.
156     *
157     * @return a Connection to the database
158     *
159     * @throws java.sql.SQLException if a database-access error occurs.
160     */
161    public Connection getConnection() throws SQLException {
162        return getConnection(getUser(), getPassword());
163    }
164 
165    /**
166     * Attempt to establish a database connection in a non-pooling, non-distributed environment.
167     *
168     * @param user     the database user on whose behalf the Connection is being made
169     * @param password the user's password
170     *
171     * @return a Connection to the database
172     *
173     * @throws java.sql.SQLException if a database-access error occurs.
174     */
175    public Connection getConnection(String user, String password) throws SQLException {
176        // Jdbc 2 connections will write driver trace info on a
177        // datasource-wide basis using the jdbc 2 data source log writer.
178        // This log writer may be narrowed to the connection-level
179        // This log writer will be passed to the agent constructor.
180        
181        try
182        {
183            LogWriter dncLogWriter = super.computeDncLogWriterForNewConnection("_sds");
184            updateDataSourceValues(tokenizeAttributes(getConnectionAttributes(), null));
185            return ClientDriver.getFactory().newNetConnection
186                    ((NetLogWriter) dncLogWriter, user,
187                    password, this, -1, false);
188        }
189        catch(SqlException se)
190        {
191            throw se.getSQLException();
192        }
193        
194    }
195 
196}
197 

[all classes][org.apache.derby.jdbc]
EMMA 2.0.5312 (C) Vladimir Roubtsov