restSQL 0.7.4 fixes restsql#7 and adds Java API examples

build.properties

@@ -1,5 +1,5 @@
 # restsql build.properties
-build.version=0.7.3
+build.version=0.7.4
 
 compile.classpath=lib/servlet-api.jar;lib/jersey-server-1.5.jar;lib/jsr311-api-1.1.1.jar;lib/commons-logging-1.1.1.jar;../restsql/lib/postgresql-9.0-801.jdbc4.jar
 
@@ -9,13 +9,14 @@ javadoc.javase6.package-list.dir=doc/javadoc/javase6
 javadoc.classpath=${compile.classpath};obj/bin
 javadoc.overview=doc/javadoc/overview.html
 javadoc.destdir.api=obj/doc/javadoc/api
-javadoc.destdir.impl=obj/doc/javadoc/impl
+javadoc.destdir.full=obj/doc/javadoc/full
 javadoc.packagenames.api=org.restsql.core,org.restsql.core.sqlresource,org.restsql.security
-javadoc.packagenames.impl=${javadoc.packagenames.api},org.restsql.core.impl,org.restsql.service,org.restsql.security.impl
+javadoc.packagenames.full=${javadoc.packagenames.api},org.restsql.core.impl,org.restsql.service,org.restsql.security.impl
 
 manifest.vendor=restsql.org
 manifest.title.jar=restSQL Java API and framework implementation
 manifest.title.war=restSQL HTTP API and service implementation
 manifest.title.src=restSQL source
+manifest.title.javadoc=restSQL javadoc
 
 war.includeLibs=true

build.xml

@@ -3,13 +3,13 @@
 	<property file="build.properties" />
 	<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask" classpath="lib/jaxb-xjc.jar" />
 
-	<target name="dist" depends="compile,lib" />
+	<target name="dist" depends="compile,lib,doc,lib-doc" description="generates distribution files" />
 
-	<target name="clean">
+	<target name="clean" description="deletes output dir">
 		<delete dir="obj" failonerror="false" includeEmptyDirs="true" quiet="true" />
 	</target>
 
-	<target name="compile">
+	<target name="compile" description="compiles sources">
 		<!-- Create output dir -->
 		<mkdir dir="obj/bin" />
 
@@ -23,10 +23,12 @@
 		</copy>
 
 		<!-- Compile -->
-		<javac srcdir="src" destdir="obj/bin" classpath="${compile.classpath}" debug="true" />
+		<javac srcdir="src" destdir="obj/bin" classpath="${compile.classpath}" debug="true">
+			<compilerarg line="-Xlint:all" />
+		</javac>
 	</target>
 
-	<target name="compile-schema">
+	<target name="compile-schema" description="executes xjc on xml files">
 		<!-- Create output dir -->
 		<mkdir dir="obj/bin" />
 
@@ -37,7 +39,7 @@
 		</xjc>
 	</target>
 
-	<target name="lib" depends="lib-war,lib-src">
+	<target name="lib" depends="lib-war,lib-src" description="generates binary libs and war">
 		<!-- Create output dir -->
 		<mkdir dir="obj/lib" />
 
@@ -121,14 +123,36 @@
 		</jar>
 	</target>
 
-	<target name="doc">
+	<target name="lib-doc" description="generates full javadoc jar">
+		<!-- Create output dir -->
+		<mkdir dir="obj/lib" />
+
+		<!-- Create JAR -->
+		<jar destfile="obj/lib/restsql-${build.version}-javadoc.jar">
+			<fileset dir="${javadoc.destdir.full}" />
+			<fileset file="CONTRIBUTORS.txt" />
+			<fileset file="LICENSE.txt" />
+			<fileset file="README.txt" />
+			<manifest>
+				<attribute name="Built-By" value="${user.name}" />
+				<attribute name="Specification-Vendor" value="${manifest.vendor}" />
+				<attribute name="Specification-Title" value="${manifest.title.javadoc}" />
+				<attribute name="Specification-Version" value="${build.version}" />
+				<attribute name="Implementation-Vendor" value="${manifest.vendor}" />
+				<attribute name="Implementation-Title" value="${manifest.title.javadoc}" />
+				<attribute name="Implementation-Version" value="${build.version}" />
+			</manifest>
+		</jar>
+	</target>
+
+	<target name="doc" description="generates javadoc">
 		<antcall target="-doc">
 			<param name="destdir" value="${javadoc.destdir.api}" />
 			<param name="packagenames" value="${javadoc.packagenames.api}" />
 		</antcall>
 		<antcall target="-doc">
-			<param name="destdir" value="${javadoc.destdir.impl}" />
-			<param name="packagenames" value="${javadoc.packagenames.impl}" />
+			<param name="destdir" value="${javadoc.destdir.full}" />
+			<param name="packagenames" value="${javadoc.packagenames.full}" />
 		</antcall>
 	</target>
 
@@ -143,5 +167,5 @@
 			<tag name="todo" scope="all" description="To do:" />
 		</javadoc>
 	</target>
-
+	
 </project>

doc/javadoc/overview.html

@@ -1,6 +1,6 @@
 <html>
 <body>
-<p>restSQL is an ultra-lightweight data access layer for HTTP clients. restSQL is a persistence framework or engine in the middle tier of a classic three tier architecture: client, application server and database. It may also be embedded in any middle-tier as a Java library.</p>
+<p>restSQL is an ultra-lightweight data access layer for HTTP and Java clients. restSQL is a persistence framework or engine in the middle tier of a classic three tier architecture: client, application server and database. It may also be embedded in any middle-tier as a Java library.</p>
 
 <h4>What it is</h4>
 <ul>

src/org/restsql/core/ColumnMetaData.java

@@ -49,6 +49,9 @@ public interface ColumnMetaData {
 	/** Returns true if column is a character string, for example char or varchar. */
 	public boolean isCharType();
 
+	/** Returns true if column is a date, time or timestamp. */
+	public boolean isDateTimeType();
+
 	/**
 	 * Returns true for foreign key columns not declared in the SQL Resource query but added by the framework. These are
 	 * required for writes to child extensions, parent extensions and and one-to-many child tables.

src/org/restsql/core/Config.java

@@ -30,7 +30,7 @@ public class Config {
 	public static final String DEFAULT_LOGGING_DIR = "/var/log/restsql";
 	public static final String DEFAULT_LOGGING_FACILITY = "log4j";
 	public static final String DEFAULT_REQUEST_FACTORY = "org.restsql.core.impl.RequestFactoryImpl";
-	public static final String DEFAULT_REQUEST_LOGGER_FACTORY = "org.restsql.core.impl.RequestLoggerFactoryImpl";
+	public static final String DEFAULT_REQUEST_LOGGER = "org.restsql.core.impl.RequestLoggerImpl";
 	public static final String DEFAULT_REQUEST_USE_XML_SCHEMA = "false";
 	public static final String DEFAULT_RESPONSE_USE_XML_DIRECTIVE = "false";
 	public static final String DEFAULT_RESPONSE_USE_XML_SCHEMA = "false";
@@ -52,7 +52,7 @@ public class Config {
 	public static final String KEY_LOGGING_DIR = "logging.dir";
 	public static final String KEY_LOGGING_FACILITY = "logging.facility";
 	public static final String KEY_REQUEST_FACTORY = "org.restsql.core.Factory.RequestFactory";
-	public static final String KEY_REQUEST_LOGGER_FACTORY = "org.restsql.core.Factory.RequestLoggerFactory";
+	public static final String KEY_REQUEST_LOGGER = "org.restsql.core.RequestLogger";
 	public static final String KEY_REQUEST_USE_XML_SCHEMA = "request.useXmlDirective";
 	public static final String KEY_RESPONSE_USE_XML_DIRECTIVE = "response.useXmlDirective";
 	public static final String KEY_RESPONSE_USE_XML_SCHEMA = "response.useXmlSchema";

src/org/restsql/core/Factory.java

@@ -6,9 +6,6 @@
 import java.sql.SQLException;
 import java.util.List;
 
-import javax.servlet.http.HttpServletRequest;
-import javax.ws.rs.core.MultivaluedMap;
-
 import org.restsql.core.Request.Type;
 import org.restsql.core.sqlresource.SqlResourceDefinition;
 
@@ -59,32 +56,9 @@ public static Request getRequestForChild(final Type type, final String sqlResour
 	}
 
 	/** Returns request logger. */
-	public static RequestLogger getRequestLogger(final HttpServletRequest request) {
-		final RequestLoggerFactory requestLoggerFactory = (RequestLoggerFactory) getInstance(
-				Config.KEY_REQUEST_LOGGER_FACTORY, Config.DEFAULT_REQUEST_LOGGER_FACTORY);
-		return requestLoggerFactory.getRequestLogger(request);
-	}
-
-	/** Returns request logger. */
-	public static RequestLogger getRequestLogger(final HttpServletRequest request,
-			final MultivaluedMap<String, String> formParams) {
-		final RequestLoggerFactory requestLoggerFactory = (RequestLoggerFactory) getInstance(
-				Config.KEY_REQUEST_LOGGER_FACTORY, Config.DEFAULT_REQUEST_LOGGER_FACTORY);
-		return requestLoggerFactory.getRequestLogger(request, formParams);
-	}
-
-	/** Returns request logger. */
-	public static RequestLogger getRequestLogger(final HttpServletRequest request, final String requestBody) {
-		final RequestLoggerFactory requestLoggerFactory = (RequestLoggerFactory) getInstance(
-				Config.KEY_REQUEST_LOGGER_FACTORY, Config.DEFAULT_REQUEST_LOGGER_FACTORY);
-		return requestLoggerFactory.getRequestLogger(request, requestBody);
-	}
-
-	/** Returns request logger. */
-	public static RequestLogger getRequestLogger(final String client, final String method, final String uri) {
-		final RequestLoggerFactory requestLoggerFactory = (RequestLoggerFactory) getInstance(
-				Config.KEY_REQUEST_LOGGER_FACTORY, Config.DEFAULT_REQUEST_LOGGER_FACTORY);
-		return requestLoggerFactory.getRequestLogger(client, method, uri);
+	public static RequestLogger getRequestLogger() {
+		return (RequestLogger) newInstance(Config.KEY_REQUEST_LOGGER,
+				Config.DEFAULT_REQUEST_LOGGER);
 	}
 
 	/** Creates SqlBuilder instance. */
@@ -161,18 +135,6 @@ public Request getRequestForChild(Type type, String sqlResource, List<NameValueP
 				RequestLogger requestLogger);
 	}
 
-	/** Creates request loggers. */
-	public interface RequestLoggerFactory {
-		public RequestLogger getRequestLogger(final HttpServletRequest request);
-
-		public RequestLogger getRequestLogger(final HttpServletRequest request,
-				final MultivaluedMap<String, String> formParams);
-
-		public RequestLogger getRequestLogger(final HttpServletRequest request, final String requestBody);
-
-		public RequestLogger getRequestLogger(final String client, final String method, final String uri);
-	}
-
 	/** Creates SQL Resource objects. */
 	public interface SqlResourceFactory {
 		public SqlResource getSqlResource(final String resName) throws SqlResourceFactoryException,

src/org/restsql/core/RequestLogger.java

@@ -1,29 +1,51 @@
 /* Copyright (c) restSQL Project Contributors. Licensed under MIT. */
-package org.restsql.core;
-
-/**
- * Logs request for troubleshooting applications. The implementation logs requests to access, error and trace logs.
- * 
- * @author Mark Sawers
- */
-public interface RequestLogger {
-	/**
-	 * Adds sql statement.
-	 */
-	public void addSql(final String sql);
-
+package org.restsql.core;
+
+import java.util.List;
+
+/**
+ * Logs request for troubleshooting applications. The implementation logs requests to access, error and trace logs.
+ * 
+ * @author Mark Sawers
+ */
+public interface RequestLogger {
+	/**
+	 * Adds a SQL statement generated during request processing. Used by the framework.
+	 */
+	public void addSql(final String sql);
+
 	/**
-	 * Logs exceptional response without an exception.
+	 * Returns list of SQL statements generated during request processing. Intended for Java API clients.
+	 */
+	public List<String> getSql();
+
+	/**
+	 * Logs exceptional response without an exception. Used by the service or Java API client.
 	 */
 	public void log(final int responseCode);
 
-	/**
-	 * Logs exceptional response with an exception.
-	 */
-	public void log(final int responseCode, final Exception exception);
-
-	/**
-	 * Logs normal response.
-	 */
-	public void log(final String responseBody);
-}
+	/**
+	 * Logs exceptional response with an exception. Used by the service or Java API client.
+	 */
+	public void log(final int responseCode, final Exception exception);
+
+	/**
+	 * Logs normal response. Used by the service or Java API client.
+	 */
+	public void log(final String responseBody);
+
+	/**
+	 * Sets request attributes. Used by the service or Java API clients.
+	 */
+	public void setRequestAttributes(String client, String method, String uri);
+
+	/**
+	 * Sets request attributes. Used by the service or Java API clients.
+	 * 
+	 * @param client IP or host name
+	 * @param method HTTP method
+	 * @param uri request URI
+	 * @param requestBody request body, e.g. XML or JSON
+	 */
+	public void setRequestAttributes(String client, String method, String uri, String requestBody);
+}

src/org/restsql/core/impl/AbstractSqlResourceMetaData.java

@@ -141,7 +141,7 @@ public void setDefinition(String resName, final SqlResourceDefinition definition
 		}
 		hierarchical = getChild() != null;
 	}
-	
+
 	// Protected methods for database-specific implementation
 
 	/**
@@ -336,6 +336,7 @@ private void buildPrimaryKeys(final Connection connection) throws SQLException {
 	 * @throws SQLException if a database access error occurs
 	 * @throws SqlResourceException if definition is invalid
 	 */
+	@SuppressWarnings("fallthrough")
 	private void buildTablesAndColumns(final ResultSet resultSet) throws SQLException, SqlResourceException {
 		final ResultSetMetaData resultSetMetaData = resultSet.getMetaData();
 		final int columnCount = resultSetMetaData.getColumnCount();
@@ -376,7 +377,7 @@ qualifiedTableName, tableName, getColumnName(definition, resultSetMetaData, colN
 						if (tableDef.getAlias() != null) {
 							table.setTableAlias(tableDef.getAlias());
 						}
-						// fall through
+						// fall through
 					case ParentExtension:
 						parentPlusExtTables.add(table);
 						break;

src/org/restsql/core/impl/ColumnMetaDataImpl.java

@@ -119,38 +119,47 @@ public class ColumnMetaDataImpl implements ColumnMetaData {
 		nonqueriedForeignKey = true;
 	}
 
+	@Override
 	public String getColumnLabel() {
 		return columnLabel;
 	}
 
+	@Override
 	public String getColumnName() {
 		return columnName;
 	}
 
+	@Override
 	public int getColumnNumber() {
 		return columnNumber;
 	}
 
+	@Override
 	public int getColumnType() {
 		return columnType;
 	}
 
+	@Override
 	public String getColumnTypeName() {
 		return columnTypeName;
 	}
 
+	@Override
 	public String getDatabaseName() {
 		return databaseName;
 	}
 
+	@Override
 	public String getQualifiedTableName() {
 		return qualifiedTableName;
 	}
 
+	@Override
 	public String getTableName() {
 		return tableName;
 	}
 
+	@Override
 	public boolean isCharType() {
 		boolean charType = false;
 		switch (columnType) {
@@ -169,10 +178,28 @@ public boolean isCharType() {
 		return charType;
 	}
 
+	@Override
+	public boolean isDateTimeType() {
+		boolean dateTimeType = false;
+		switch (columnType) {
+			case Types.TIME:
+			case Types.TIMESTAMP:
+			case Types.DATE:
+				dateTimeType = true;
+				break;
+
+			default:
+				// do nothing
+		}
+		return dateTimeType;
+	}
+
+	@Override
 	public boolean isNonqueriedForeignKey() {
 		return nonqueriedForeignKey;
 	}
 
+	@Override
 	public boolean isPrimaryKey() {
 		return primaryKey;
 	}