Merge branch 'release-3.0.0-EA3'

CONTRIBUTING.md

@@ -0,0 +1,124 @@
+= Contributor License Agreement ("Agreement")
+
+Thank you for your interest in an open source project administered by
+the MarkLogic Corporation (the "Project"). This Agreement states the
+terms under which you, the person listed below, may contribute to the
+Project any software, modifications or additions, bug fixes,
+documentation, or any other materials that you provide (whether
+electronically, verbally, or in written form) to MarkLogic
+Corporation ("MarkLogic" or "us") related to the Project (each a
+"Contribution"). This license is for your protection as well as the
+protection of MarkLogic and its licensees. This Agreement does not
+otherwise change your rights to use your own Contributions for any
+other purpose. Please complete the following information about you and
+the Contributions and either (a) sign electronically by filling out
+the form below or (b) sign and submit the form to the contact
+information below.
+
+If you develop software or create software code as a part of your
+employment, or if your employer is in the business of developing
+software, or otherwise may claim rights in the Contributions, please
+provide information about your employer's policy on contributing to
+open source projects below, including the name of the supervisor to
+contact in connection with such contributions.
+
+If you have questions about this Agreement, please contact us at
+[email protected].
+
+.You and MarkLogic acknowledge and agree:
+. Control of the Project. We, in our sole discretion, determine the
+  Contributions that will be included in the Project. You understand
+  that this Agreement, and your submission of any Contribution, does
+  not guarantee that any such Contributions will be included in the
+  Project.
+. License Grants. You hereby grant to MarkLogic, a perpetual,
+  non-exclusive, irrevocable, worldwide, royalty-free and fully
+  paid-up, sublicenseable, and transferable license under all of your
+  relevant intellectual property rights (including copyright, patent,
+  trade secret, and any other rights), to use, copy, modify, prepare
+  derivative works of, distribute and publicly perform and publicly
+  display your Contributions on any licensing terms, in our sole
+  discretion, including without limitation: (a) the GNU General Public
+  License, the GNU Lesser General Public License, the Common Public
+  License, the MIT License, the Apache License, or the Berkeley
+  Software Distribution license; and (b) binary, proprietary, or
+  commercial licenses. You hereby grant to MarkLogic and to recipients
+  of the Project a perpetual, worldwide, non-exclusive, fully-paid up
+  and royalty-free, irrevocable patent license to make, have made, use,
+  offer to sell, sell, import, and otherwise transfer the Project,
+  where such license applies only to those patent claims licensable by
+  you that are necessarily infringed by your Contributions alone or by
+  combination of your Contributions with the Project.
+. Ownership. Except for the licenses granted herein, you reserve all
+  right, title, and interest in and to your Contributions.
+. Your Representations. You represent that you are able and entitled to
+  grant us the above license rights. You represent that your
+  Contributions are your original works of authorship, and to your
+  knowledge, no other person claims, or has the right to claim, any
+  right in any intellectual property right, including without
+  limitation invention or patent rights, related to your Contributions.
+  You also represent that you are not legally obligated, whether by
+  entering into an agreement or otherwise, in any way that conflicts
+  with the terms of the foregoing license grant. If your employer has
+  rights to intellectual property that you create, you represent that
+  you have received permission to make your Contributions on behalf of
+  that employer, or that your employer has waived such rights for your
+  Contributions.
+. No Implied Warranties. MarkLogic acknowledges that, except as
+  explicitly described in this Agreement, your Contribution is
+  provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+  ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
+  ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT,
+  MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+
+== Complete and sign
+
+----
+Full name:      ____________________________________________________________
+
+Email address:  ____________________________________________________________
+
+Postal address:
+
+               Street: _____________________________________________________
+
+                       _____________________________________________________
+
+                 City: _____________________________________________________
+
+    State or province: _____________________________________________________
+
+          Postal code: _____________________________________________________
+
+              Country: _____________________________________________________
+
+Phone number:   ____________________________________________________________
+
+
+Corporate contributor information:
+
+                ____________________________________________________________
+
+                ____________________________________________________________
+
+                ____________________________________________________________
+
+                ____________________________________________________________
+
+
+Signature:      ____________________________________________________________
+
+----
+
+== Signing Alternatives
+
+You may print the document and send the original to:
+
+MarkLogic Corporation +
+Attn: Contract Administrator +
+999 Skyway Road, +
+San Carlos, CA 94070 +
+USA +
+
+You may also send a scanned PDF of the form to
+[email protected].

README.md

@@ -52,3 +52,5 @@ You might want to skip the tests until you have configured a test database and R
 
 > mvn package -Dmaven.test.skip=true
 
+## Support
+The MarkLogic Java Client API is maintained by MarkLogic Engineering and distributed under the [Apache 2.0 license](https://github.com/marklogic/java-client-api/blob/master/LICENSE). It is designed for use in production applications with MarkLogic Server. Everyone is encouraged to file bug reports, feature requests, and pull requests through GitHub. This input is critical and will be carefully considered, but we can’t promise a specific resolution or timeframe for any request. In addition, MarkLogic provides technical support for [release tags](https://github.com/marklogic/java-client-api/releases) of the Java Client API to licensed customers under the terms outlined in the [Support Handbook](http://www.marklogic.com/files/Mark_Logic_Support_Handbook.pdf). For more information or to sign up for support, visit [help.marklogic.com](http://help.marklogic.com).

pom.xml

@@ -4,11 +4,11 @@
 	<groupId>com.marklogic</groupId>
 	<artifactId>client-api-java</artifactId>
 	<packaging>jar</packaging>
-	<version>3.0.0-EA2</version>
+	<version>3.0.0-EA3</version>
 	<name>client-api-java</name>
 	<url>http://developer.marklogic.com</url>
 	<properties>
-		<javadoc-title>${project.name} 2.0 ${maven.build.timestamp}</javadoc-title>
+		<javadoc-title>${project.name} 3.0.0</javadoc-title>
 		<maven.build.timestamp.format>yyyy-MM-dd</maven.build.timestamp.format>
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <github.global.server>github</github.global.server>
@@ -138,7 +138,7 @@
             <plugin>
                 <groupId>com.github.github</groupId>
                 <artifactId>site-maven-plugin</artifactId>
-                <version>0.9</version>
+                <version>0.10</version>
                 <configuration>
                     <message>Maven artifacts for ${project.version}</message>
                     <merge>true</merge>
@@ -161,8 +161,44 @@
         </plugin>
 		</plugins>
 	</build>
+	<profiles>
+		<profile>
+			<id>Java 8</id>
+			<activation>
+				<jdk>1.8</jdk>
+			</activation>
+			<properties>
+				<!-- Disable Java 8 overly strict javadoc linter when building with Java 8
+					http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
+					-->
+				<additionalparam>-Xdoclint:none</additionalparam>
+			</properties>
+		</profile>
+	</profiles>
 	<dependencies>
 		<!-- direct build / run dependencies -->
+        <!--
+		<dependency>
+			<groupId>com.sun.jersey</groupId>
+			<artifactId>jersey-client</artifactId>
+			<version>1.17</version>
+		</dependency>
+		<dependency>
+			<groupId>com.sun.jersey.contribs</groupId>
+			<artifactId>jersey-apache-client4</artifactId>
+			<version>1.17</version>
+		</dependency>
+		<dependency>
+			<groupId>com.sun.jersey.contribs</groupId>
+			<artifactId>jersey-multipart</artifactId>
+			<version>1.17</version>
+		</dependency>
+		<dependency>
+			<groupId>org.glassfish.jersey.media</groupId>
+			<artifactId>jersey-media-multipart</artifactId>
+			<version>2.12</version>
+		</dependency>
+        -->
 		<dependency>
 			<groupId>com.sun.jersey</groupId>
 			<artifactId>jersey-client</artifactId>
@@ -181,7 +217,7 @@
 		<dependency>
 			<groupId>ch.qos.logback</groupId>
 			<artifactId>logback-classic</artifactId>
-			<version>1.0.12</version>
+			<version>1.1.2</version>
 		</dependency>
 		<dependency>
 			<groupId>commons-logging</groupId>
@@ -203,11 +239,6 @@
 			<artifactId>mimepull</artifactId>
 			<version>1.9.4</version>
 		</dependency>
-		<dependency>
-			<groupId>ch.qos.logback</groupId>
-			<artifactId>logback-core</artifactId>
-			<version>1.0.12</version>
-		</dependency>
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-api</artifactId>

src/main/java/com/marklogic/client/DatabaseClient.java

@@ -24,6 +24,7 @@
 import com.marklogic.client.document.JSONDocumentManager;
 import com.marklogic.client.document.TextDocumentManager;
 import com.marklogic.client.document.XMLDocumentManager;
+import com.marklogic.client.eval.ServerEvaluationCall;
 import com.marklogic.client.extensions.ResourceManager;
 import com.marklogic.client.admin.ExtensionMetadata;
 import com.marklogic.client.query.QueryManager;
@@ -106,7 +107,7 @@ public interface DatabaseClient {
      * Creates a manager for configuring the REST server for the database. The
      * ServerConfigurationManager can persist query options and transforms or
      * set properties of the server. The application must have rest-admin
-     * privilieges to use the ServerConfigurationManager.
+     * privileges to use the ServerConfigurationManager.
      * 
      * @return	a manager for the server properties or administrative resources
      */
@@ -177,4 +178,13 @@ public <T extends ResourceManager> T init(String resourceName, T resourceManager
      * @return	the object implementing communication with the server 
      */
     public Object getClientImplementation();
+
+    /**
+     * Creates a ServerEvaluationCall for eval and invoke of server-side xquery or 
+     * javascript code.  Eval requires the xdbc:eval privilege and invoke requires the
+     * xdbc:invoke privilege.  If this DatabaseClient is pointed at a database different
+     * than the default for this REST server, you will need the xdbc:eval-in or xdbc:invoke-in
+     * privilege.
+     */
+	public ServerEvaluationCall newServerEval();
 }

src/main/java/com/marklogic/client/DatabaseClientFactory.java

@@ -207,7 +207,21 @@ private DatabaseClientFactory() {
 	 * @return	a new client for making database requests
 	 */
 	static public DatabaseClient newClient(String host, int port) {
-		return newClient(host, port, null, null, null, null, null);
+		return newClient(host, port, null, null, null, null, null, null);
+	}
+
+	/**
+	 * Creates a client to access the database by means of a REST server
+	 * without any authentication. Such clients can be convenient for
+	 * experimentation but should not be used in production. 
+	 * 
+	 * @param host	the host with the REST server
+	 * @param port	the port for the REST server
+	 * @param database	the database to access (default: configured database for the REST server)
+	 * @return	a new client for making database requests
+	 */
+	static public DatabaseClient newClient(String host, int port, String database) {
+		return newClient(host, port, database, null, null, null, null, null);
 	}
 
 	/**
@@ -221,7 +235,21 @@ static public DatabaseClient newClient(String host, int port) {
 	 * @return	a new client for making database requests
 	 */
 	static public DatabaseClient newClient(String host, int port, String user, String password, Authentication type) {
-		return newClient(host, port, user, password, type, null, null);
+		return newClient(host, port, null, user, password, type, null, null);
+	}
+	/**
+	 * Creates a client to access the database by means of a REST server.
+	 * 
+	 * @param host	the host with the REST server
+	 * @param port	the port for the REST server
+	 * @param database	the database to access (default: configured database for the REST server)
+	 * @param user	the user with read, write, or administrative privileges
+	 * @param password	the password for the user
+	 * @param type	the type of authentication applied to the request
+	 * @return	a new client for making database requests
+	 */
+	static public DatabaseClient newClient(String host, int port, String database, String user, String password, Authentication type) {
+		return newClient(host, port, database, user, password, type, null, null);
 	}
 	/**
 	 * Creates a client to access the database by means of a REST server.
@@ -235,7 +263,22 @@ static public DatabaseClient newClient(String host, int port, String user, Strin
 	 * @return	a new client for making database requests
 	 */
 	static public DatabaseClient newClient(String host, int port, String user, String password, Authentication type, SSLContext context) {
-		return newClient(host, port, user, password, type, context, SSLHostnameVerifier.COMMON);
+		return newClient(host, port, null, user, password, type, context, SSLHostnameVerifier.COMMON);
+	}
+	/**
+	 * Creates a client to access the database by means of a REST server.
+	 * 
+	 * @param host	the host with the REST server
+	 * @param port	the port for the REST server
+	 * @param database	the database to access (default: configured database for the REST server)
+	 * @param user	the user with read, write, or administrative privileges
+	 * @param password	the password for the user
+	 * @param type	the type of authentication applied to the request
+	 * @param context	the SSL context for authenticating with the server
+	 * @return	a new client for making database requests
+	 */
+	static public DatabaseClient newClient(String host, int port, String database, String user, String password, Authentication type, SSLContext context) {
+		return newClient(host, port, database, user, password, type, context, SSLHostnameVerifier.COMMON);
 	}
 	/**
 	 * Creates a client to access the database by means of a REST server.
@@ -250,14 +293,32 @@ static public DatabaseClient newClient(String host, int port, String user, Strin
 	 * @return	a new client for making database requests
 	 */
 	static public DatabaseClient newClient(String host, int port, String user, String password, Authentication type, SSLContext context, SSLHostnameVerifier verifier) {
-		DatabaseClientImpl client = newClientImpl(host, port, user, password, type, context, verifier);
+		DatabaseClientImpl client = newClientImpl(host, port, null, user, password, type, context, verifier);
+		client.setHandleRegistry(getHandleRegistry().copy());
+		return client;
+	}
+	/**
+	 * Creates a client to access the database by means of a REST server.
+	 * 
+	 * @param host	the host with the REST server
+	 * @param port	the port for the REST server
+	 * @param database	the database to access (default: configured database for the REST server)
+	 * @param user	the user with read, write, or administrative privileges
+	 * @param password	the password for the user
+	 * @param type	the type of authentication applied to the request
+	 * @param context	the SSL context for authenticating with the server
+	 * @param verifier	a callback for checking hostnames
+	 * @return	a new client for making database requests
+	 */
+	static public DatabaseClient newClient(String host, int port, String database, String user, String password, Authentication type, SSLContext context, SSLHostnameVerifier verifier) {
+		DatabaseClientImpl client = newClientImpl(host, port, database, user, password, type, context, verifier);
 		client.setHandleRegistry(getHandleRegistry().copy());
 		return client;
 	}
-	static private DatabaseClientImpl newClientImpl(String host, int port, String user, String password, Authentication type, SSLContext context, SSLHostnameVerifier verifier) {
+	static private DatabaseClientImpl newClientImpl(String host, int port, String database, String user, String password, Authentication type, SSLContext context, SSLHostnameVerifier verifier) {
 		logger.debug("Creating new database client for server at "+host+":"+port);
 		JerseyServices services = new JerseyServices();
-		services.connect(host, port, user, password, type, context, verifier);
+		services.connect(host, port, database, user, password, type, context, verifier);
 
 		if (clientConfigurator != null) {
 			((HttpClientConfigurator) clientConfigurator).configure(
@@ -337,6 +398,7 @@ static public class Bean implements Serializable {
 
 		private           String                host;
 		private           int                   port;
+		private           String                database;
 		private           String                user;
 		private           String                password;
 		private           Authentication        authentication;
@@ -510,7 +572,7 @@ public void registerDefaultHandles() {
 		 * @return	a new client for making database requests
 		 */
 		public DatabaseClient newClient() {
-			DatabaseClientImpl client = newClientImpl(host, port, user, password, authentication, context, verifier);
+			DatabaseClientImpl client = newClientImpl(host, port, database, user, password, authentication, context, verifier);
 			client.setHandleRegistry(getHandleRegistry().copy());
 
 			return client;

src/main/java/com/marklogic/client/MarkLogicBindingException.java

@@ -29,7 +29,12 @@ public class MarkLogicBindingException extends RuntimeException {
 	static final private Logger logger = LoggerFactory
 			.getLogger(MarkLogicBindingException.class);
 
+	public MarkLogicBindingException(String message, Throwable e) {
+		super(message, e);
+	}
+
 	public MarkLogicBindingException(Exception e) {
+		super(e);
 		e.printStackTrace();
 	}