README.txt

@@ -19,7 +19,7 @@ You can build Jackrabbit like this:
 
     mvn clean install
 
-You need Maven 3 (or higher) with Java 7 (or higher) for the
+You need Maven 3 (or higher) with Java 8 (or higher) for the
 build. For more instructions, please see the documentation at:
 
    http://jackrabbit.apache.org/building-jackrabbit.html

RELEASE-NOTES.txt

-Release Notes -- Apache Jackrabbit -- Version 2.14.6
+Release Notes -- Apache Jackrabbit -- Version 2.18.0
 
 Introduction
 ------------
 
-This is Apache Jackrabbit(TM) 2.14.6, a fully compliant implementation of the
+This is Apache Jackrabbit(TM) 2.18.0, a fully compliant implementation of the
 Content Repository for Java(TM) Technology API, version 2.0 (JCR 2.0) as
 specified in the Java Specification Request 283 (JSR 283).
 
-Apache Jackrabbit 2.14.6 is a patch release that contains fixes and
-improvements over Jackrabbit 2.14. Jackrabbit 2.14.x releases are
-considered stable and targeted for production use.
+Apache Jackrabbit 2.18.0 is an incremental feature release based on
+and compatible with earlier stable Jackrabbit 2.x releases. Jackrabbit
+2.18.x releases are considered stable and targeted for production use.
 
-Changes in Jackrabbit 2.14.6
+The minimum Java version for this release is Java 8. See
+
+  http://jackrabbit.apache.org/jcr/downloads.html
+  
+for maintenance versions that support earlier Java versions.
+
+
+Changes in Jackrabbit 2.18.0
 ----------------------------
 
 Bug
 
-    [JCR-4093] - IndexRule are meant to be applied based on both primaryType and minin type based inheritance. Currently it appears that only primaryType based inheritance is working
+    [JCR-4120] - Spi2DavexRepositoryServiceImpl always hardcodes the default workspace name to "default"
+    [JCR-4241] - Jacoco plugin fails with exception
+    [JCR-4242] - Build failure: unapproved license
     [JCR-4291] - FileInputStream for workspace.xml not closed in RepositoryConfig.loadWorkspaceConfig(File)
     [JCR-4317] - davex remoting fails for non-ASCII characters in node names
     [JCR-4324] - NPE on Version.getLinearPredecessor() implementation
+    [JCR-4339] - Indexing configuration condition property seems to be broken
+    [JCR-4370] - Remove extraneously set config from TestS3Ds
+    [JCR-4387] - Incorrect exception message when same-name-sibling is prevented on import
+
+New Feature
+
+    [JCR-4335] - API for direct binary access
 
 Improvement
 
     [JCR-3211] - Support HTTP proxy in SPI2DAV
+    [JCR-4001] - When using Node.getProperties(String namePattern) also child nodes are processed
+    [JCR-4237] - cleanup throws clauses of private methods
+    [JCR-4238] - use StandardCharsets to avoid having to handle UnsupportedEncodingException
+    [JCR-4239] - Suppress Tika startup warnings
+    [JCR-4249] - Introduce replacement for java.security.acl.Group
     [JCR-4253] - RepositoryConfig: add some handling for mkdir failure
+    [JCR-4287] - Improve Debug-Log in SearchIndex and MultiIndex
     [JCR-4292] - davex: preserve cause in exceptions and log affected URI
+    [JCR-4354] - VFS (commons-vfs) based FileSystem for VFS backend based Persistence Manager
+    [JCR-4355] - Javadoc fixes and improvements for new direct binary access API
+    [JCR-4369] - Avoid S3 Incomplete Read Warning
 
 Task
 
+    [JCR-4215] - Use Tika version 1.17
+    [JCR-4218] - switch bundle comparisonVersion
+    [JCR-4221] - Upgrade Apache HttpComponents to 4.5.4
+    [JCR-4222] - Document reduced RMI interop with older servers after java-9 related changes
+    [JCR-4223] - Upgrade commons-fileupload dependency to 1.3.3
+    [JCR-4224] - Upgrade tomcat-servlet dependency to 7.0.82
+    [JCR-4225] - Upgrade commons-chains dependency to 1.2
+    [JCR-4226] - Upgrade tika-parsers dependency to 1.16
+    [JCR-4228] - Update Oak dependency to latest 1.0 stable release
+    [JCR-4229] - Remove Oak dependency in webapp
+    [JCR-4231] - Upgrade aws-java-sdk-s3 dependency to 1.11.241
+    [JCR-4233] - Update H2DB test dependency
+    [JCR-4236] - remove obsolete textFilterClasses config parameters
+    [JCR-4240] - IndexingQueueTest relies on Tika behavior that is changed in Tika 1.17
+    [JCR-4244] - Upgrade tomcat dependency to 8.5.24
+    [JCR-4246] - java.security.acl deprecated in Java 10, marked for removal in Java 12
+    [JCR-4247] - Update commons-io dependency
+    [JCR-4248] - Upgrade httpcore dependency to 4.4.9
+    [JCR-4250] - remove guava dependency
+    [JCR-4252] - Upgrade httpclient dependency to 4.5.5
     [JCR-4254] - Update Logback version to >= 1.2.0, SLF4J accordingly
     [JCR-4256] - create announcement mail template for releases
     [JCR-4261] - webapp: align jsons-simple dependencies internally and with oak
     [JCR-4262] - jcr-server: align org.apache.felix.scr.annotations with oak
     [JCR-4263] - jcr-server, jackrabbit-bundle: align org.osgi dependencies with oak
     [JCR-4264] - jackrabbit-standalone: align commons-cli dependency with oak
+    [JCR-4266] - Update servlet-api to 2.5
+    [JCR-4271] - Remove redundant JavaDoc link to Java 7 API
     [JCR-4272] - Upgrade surefire and failsafe plugins to 2.21.0
+    [JCR-4273] - Mention SHA512 checksums in release notes
+    [JCR-4274] - stop advertising MD5 checksums
+    [JCR-4275] - Incorrect link to KEYS in release notes
+    [JCR-4277] - stop creating MD5 checksums for releases
     [JCR-4288] - Upgrade tika-parsers dependency to 1.18
     [JCR-4290] - remove unused commons-codec dependency
     [JCR-4293] - jackrabbit-core: observation tests should not rely on mix:lockable mixin type
     [JCR-4294] - TCK tests should pass on repositories without locking support
     [JCR-4296] - Upgrade httpmime dependency to 4.5.5
+    [JCR-4299] - Update derby dependency to 10.14.2.0
+    [JCR-4301] - get rid of JSR 305 dependency
     [JCR-4302] - BTreeManager: fix Eclipse compiler error
     [JCR-4304] - update Jetty to supported version 9.2.*
     [JCR-4307] - Update animal-sniffer-maven-plugin to 1.16
+    [JCR-4312] - set baseline comparisonVersion to latest stable (2.16.1)
+    [JCR-4316] - set baseline comparisonVersion to latest stable (2.16.2)
     [JCR-4318] - Update failsafe and surefire plugin versions to 2.22.0
     [JCR-4320] - Update spotbugs plugin to 3.1.5
     [JCR-4321] - Update maven plugins from org.apache.maven.plugins
@@ -54,12 +109,48 @@ Task
     [JCR-4331] - Update httpclient dependency to 4.5.6
     [JCR-4332] - Update httpmime dependency to 4.5.6
     [JCR-4333] - Update javax.transaction dependency to 1.3
+    [JCR-4336] - Upgrade commons-dbcp dependencies
+    [JCR-4337] - Jackrabbit should compile & test on Java 11
+    [JCR-4342] - remove unused JSR 305 dependency from pom
+    [JCR-4343] - Update commons-vfs2 version to 2.2
+    [JCR-4344] - Update h2db version to latest stable 1.4.196
+    [JCR-4345] - Update mockito dependency to 2.20.0
+    [JCR-4346] - Update easymock dependency to 3.6
+    [JCR-4347] - Update com.jcraft.jsch dependency to 0.1.54
+    [JCR-4348] - Update osgi (compendium, core) dependencies
+    [JCR-4349] - Update plexus-utils dependency to 3.1.0
+    [JCR-4350] - jackrabbit-jcr-servlet: remove special-cased servlet-api dependency
+    [JCR-4353] - set baseline comparisonVersion to latest stable (2.16.3)
+    [JCR-4359] - update maven-bundle-plugin to 3.5.0
+    [JCR-4360] - update maven-scr-plugin to 1.26.0
+    [JCR-4361] - Update spotbugs plugin to 3.1.6
+    [JCR-4362] - Update tomcat dependency to 8.5.33
+    [JCR-4363] - Update mockito dependency to 2.21.0
+    [JCR-4364] - update org.apache.felix.scr.annotations dependency to 1.12.0
+    [JCR-4365] - Update cglib dependency to 3.2.8
+    [JCR-4367] - Update htmlunit test dependency to 2.32
+    [JCR-4368] - Update commons-cli dependency to 1.4
+    [JCR-4371] - Update tika dependency to 1.19
+    [JCR-4372] - Update mockito dependency to 2.22.0
+    [JCR-4373] - webapp: update Tomcat dependency to 8.5.34
+    [JCR-4374] - webapp: update htmlunit dependency to 2.33
+    [JCR-4375] - Update jetbrains dependency to 16.0.3
+    [JCR-4379] - Update tika dependency to 1.19.1
+    [JCR-4381] - Update failsafe and surefire plugin versions to 2.22.1
+    [JCR-4382] - Update spotbugs plugin to 3.1.7
+    [JCR-4383] - Update animal-sniffer-maven-plugin to 1.17
+    [JCR-4384] - Update maven-bundle-plugin to 4.0.0
+    [JCR-4385] - Update maven-war-plugin to 3.2.2
+    [JCR-4386] - remove unused jxr dependency
+    [JCR-4388] - Update mockito dependency to 2.23.0
 
 Sub-task
 
+    [JCR-4258] - Remove SimpleJBossAccessManager in preparation of upcoming acl changes
     [JCR-4280] - code coverage checks fail on Java 10
     [JCR-4306] - switch to findbugs replacement that is still maintained (spotbugs)
     [JCR-4338] - avoid use of javax.rmi.PortableRemoteObject (removed in Java 11)
+    [JCR-4357] - upgrade to Jacoco version compatible with Java 11
 
 
 For more detailed information about all the changes in this and other

debian/changelog

+jackrabbit (2.18.0-1) unstable; urgency=medium
+
+  * Team upload.
+  * New upstream version 2.18.0.
+  * Drop libcommons-httpclient-java. No longer needed. (Closes: #800993)
+  * Rebase servlet-api.patch.
+
+ -- Markus Koschany <apo@debian.org>  Sat, 22 Dec 2018 22:51:06 +0100
+
 jackrabbit (2.14.6-1) unstable; urgency=medium
 
   * Team upload.

debian/control

@@ -9,7 +9,6 @@ Build-Depends:
  debhelper (>= 11),
  default-jdk,
  libapache-pom-java,
- libcommons-httpclient-java,
  libmaven-bundle-plugin-java,
  libservlet3.1-java,
  libslf4j-java,

debian/copyright

@@ -71,7 +71,7 @@ License: W3C
 
 Files: debian/*
 Copyright: Copyright (C) 2011,      Damien Raude-Morvan <drazzib@debian.org>
-                         2015-2018, Markus Koschany <apo@gambaru.de>
+                         2015-2018, Markus Koschany <apo@debian.org>
 License: Apache-2.0
 
 License: Apache-2.0

debian/maven.rules

@@ -17,7 +17,6 @@
 #   junit junit jar s/3\\..*/3.x/
 
 commons-collections commons-collections jar s/3\..*/3.x/ * *
-commons-httpclient commons-httpclient jar s/3\..*/3.x/ * *
 junit junit jar s/4\..*/4.x/ * *
 org.apache apache pom s/.*/debian/ * *
 org.apache.jackrabbit jackrabbit-parent pom s/.*/debian/ * *

debian/patches/servlet-api.patch

 From: Markus Koschany <apo@debian.org>
-Date: Sun, 5 Nov 2017 14:49:24 +0100
+Date: Sat, 22 Dec 2018 23:13:36 +0100
 Subject: servlet api
 
 Compatibility patch for Debian's newer servlet API.
 
 Forwarded: no
 ---
- .../jackrabbit/webdav/WebdavRequestImpl.java       | 100 +++++++++++++++++++--
- .../jackrabbit/webdav/WebdavResponseImpl.java      |  33 +++++++
- 2 files changed, 127 insertions(+), 6 deletions(-)
+ .../jackrabbit/webdav/WebdavRequestImpl.java       | 85 ++++++++++++++++++++--
+ .../jackrabbit/webdav/WebdavResponseImpl.java      | 26 +++++++
+ 2 files changed, 105 insertions(+), 6 deletions(-)
 
+diff --git a/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavRequestImpl.java b/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavRequestImpl.java
+index f444ce0..ca8e5cd 100644
 --- a/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavRequestImpl.java
 +++ b/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavRequestImpl.java
 @@ -36,6 +36,17 @@ import javax.servlet.ServletInputStream;
@@ -39,7 +41,7 @@ Forwarded: no
  
  /**
   * <code>WebdavRequestImpl</code>...
-@@ -831,11 +844,11 @@ public class WebdavRequestImpl implement
+@@ -831,11 +844,11 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
          return httpRequest.getHeader(s);
      }
  
@@ -53,7 +55,7 @@ Forwarded: no
          return httpRequest.getHeaderNames();
      }
  
-@@ -919,7 +932,7 @@ public class WebdavRequestImpl implement
+@@ -919,7 +932,7 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
          return httpRequest.getAttribute(s);
      }
  
@@ -62,7 +64,7 @@ Forwarded: no
          return httpRequest.getAttributeNames();
      }
  
-@@ -947,7 +960,7 @@ public class WebdavRequestImpl implement
+@@ -947,7 +960,7 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
          return httpRequest.getParameter(s);
      }
  
@@ -71,7 +73,7 @@ Forwarded: no
          return httpRequest.getParameterNames();
      }
  
-@@ -955,7 +968,7 @@ public class WebdavRequestImpl implement
+@@ -955,7 +968,7 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
          return httpRequest.getParameterValues(s);
      }
  
@@ -80,7 +82,7 @@ Forwarded: no
          return httpRequest.getParameterMap();
      }
  
-@@ -999,7 +1012,7 @@ public class WebdavRequestImpl implement
+@@ -999,7 +1012,7 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
          return httpRequest.getLocale();
      }
  
@@ -89,25 +91,10 @@ Forwarded: no
          return httpRequest.getLocales();
      }
  
-@@ -1014,4 +1027,79 @@ public class WebdavRequestImpl implement
-     public String getRealPath(String s) {
-         return httpRequest.getRealPath(s);
+@@ -1030,4 +1043,64 @@ public class WebdavRequestImpl implements WebdavRequest, DavConstants {
+     public int getLocalPort() {
+         return httpRequest.getLocalPort();
      }
-+    // Compat Servlet 2.4
-+    public int getRemotePort() {
-+       return httpRequest.getRemotePort();
-+    }
-+    public int getLocalPort() {
-+       return httpRequest.getLocalPort();
-+    }
-+
-+    public String getLocalName() {
-+       return httpRequest.getLocalName();
-+    }
-+
-+    public String getLocalAddr() {
-+       return httpRequest.getLocalAddr();
-+    }
 +    //---< servlet 3.1 >---
 +    public Part getPart(String name) throws IOException, IllegalStateException, ServletException {
 +        throw new UnsupportedOperationException("Not supported.");
@@ -169,6 +156,8 @@ Forwarded: no
 +        throw new UnsupportedOperationException("Not supported.");
 +    }
  }
+diff --git a/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavResponseImpl.java b/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavResponseImpl.java
+index 6c03aed..cc29c0c 100644
 --- a/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavResponseImpl.java
 +++ b/jackrabbit-webdav/src/main/java/org/apache/jackrabbit/webdav/WebdavResponseImpl.java
 @@ -44,6 +44,8 @@ import java.io.PrintWriter;
@@ -180,17 +169,10 @@ Forwarded: no
  
  /**
   * WebdavResponseImpl implements the <code>WebdavResponse</code> interface.
-@@ -311,4 +313,35 @@ public class WebdavResponseImpl implemen
-     public Locale getLocale() {
-         return httpResponse.getLocale();
+@@ -319,4 +321,28 @@ public class WebdavResponseImpl implements WebdavResponse {
+     public void setCharacterEncoding(String charset) {
+         httpResponse.setCharacterEncoding(charset);
      }
-+    // Compat Servlet 2.4
-+    public void setCharacterEncoding(String env) {
-+       httpResponse.setCharacterEncoding(env);
-+    }
-+    public String getContentType() {
-+       return httpResponse.getContentType();
-+    }
 +    //---< servlet 3.0 >---
 +    public Collection<String> getHeaderNames() {
 +        throw new UnsupportedOperationException("Not supported.");

debian/rules

 #!/usr/bin/make -f
 
 export JAVA_HOME=/usr/lib/jvm/default-java
-export CLASSPATH=/usr/share/java/slf4j-api.jar:/usr/share/java/servlet-api-3.1.jar:/usr/share/java/commons-httpclient.jar:/usr/share/java/bnd.annotation.jar
+export CLASSPATH=/usr/share/java/slf4j-api.jar:/usr/share/java/servlet-api-3.1.jar:/usr/share/java/bnd.annotation.jar
 
 %:
 	dh $@ --buildsystem=maven

jackrabbit-api/pom.xml

@@ -26,7 +26,7 @@
   <parent>
     <groupId>org.apache.jackrabbit</groupId>
     <artifactId>jackrabbit-parent</artifactId>
-    <version>2.14.6</version>
+    <version>2.18.0</version>
     <relativePath>../jackrabbit-parent/pom.xml</relativePath>
   </parent>
   <artifactId>jackrabbit-api</artifactId>
@@ -59,16 +59,16 @@
       <artifactId>jcr</artifactId>
     </dependency>
     <dependency>
-      <groupId>biz.aQute</groupId>
-      <artifactId>bndlib</artifactId>
+      <groupId>org.osgi</groupId>
+      <artifactId>org.osgi.annotation</artifactId>
       <scope>provided</scope>
     </dependency>
 
-    <!-- Findbugs annotations -->
+    <!-- nullability, see JCR-4301 -->
     <dependency>
-      <groupId>com.google.code.findbugs</groupId>
-      <artifactId>jsr305</artifactId>
-      <scope>provided</scope>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>16.0.3</version>
     </dependency>
   </dependencies>
 </project>

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/JackrabbitSession.java

@@ -19,7 +19,6 @@ package org.apache.jackrabbit.api;
 import org.apache.jackrabbit.api.security.user.UserManager;
 import org.apache.jackrabbit.api.security.principal.PrincipalManager;
 
-import javax.annotation.Nonnull;
 import javax.jcr.Item;
 import javax.jcr.Node;
 import javax.jcr.Property;
@@ -28,6 +27,8 @@ import javax.jcr.AccessDeniedException;
 import javax.jcr.RepositoryException;
 import javax.jcr.UnsupportedRepositoryOperationException;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Jackrabbit specific extension of the JCR {@link javax.jcr.Session} interface.
  */
@@ -189,7 +190,7 @@ public interface JackrabbitSession extends Session {
      * @throws RepositoryException if an error occurs.
      * @see Session#hasPermission(String, String)
      */
-    public boolean hasPermission(@Nonnull String absPath, @Nonnull String... actions) throws RepositoryException;
+    public boolean hasPermission(@NotNull String absPath, @NotNull String... actions) throws RepositoryException;
 
     /**
      * Returns the <code>PrincipalManager</code> for the current <code>Session</code>.

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/JackrabbitValueFactory.java

+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.jackrabbit.api;
+
+import java.io.InputStream;
+import javax.jcr.AccessDeniedException;
+import javax.jcr.Binary;
+import javax.jcr.RepositoryException;
+import javax.jcr.Session;
+import javax.jcr.ValueFactory;
+
+import org.apache.jackrabbit.api.binary.BinaryDownloadOptions;
+import org.apache.jackrabbit.api.binary.BinaryUpload;
+import org.apache.jackrabbit.api.binary.BinaryDownload;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Defines optional functionality that a {@link ValueFactory} may choose to
+ * provide. A {@link ValueFactory} may also implement this interface without
+ * supporting all of the capabilities in this interface. Each method of the
+ * interface describes the behavior of that method if the underlying capability
+ * is not available.
+ *
+ * <p>
+ * This interface defines the following optional features:
+ * <ul>
+ *     <li>
+ *         Direct Binary Access - enable a client to upload or download binaries
+ *         directly to/from a storage location
+ *     </li>
+ * </ul>
+ *
+ * <p>
+ * The features are described in more detail below.
+ *
+ * <h2>Direct Binary Access</h2>
+ *
+ * The Direct Binary Access feature provides the capability for a client to
+ * upload or download binaries directly to/from a storage location. For example,
+ * this might be a cloud storage providing high-bandwidth direct network access.
+ * This API allows for requests to be authenticated and for access permission
+ * checks to take place within the repository, but for clients to then access
+ * the storage location directly.
+ *
+ * <p>
+ * The feature consists of two parts, download and upload.
+ *
+ * <h3>Direct Binary Download</h3>
+ *
+ * This feature enables remote clients to download binaries directly from a
+ * storage location without streaming the binary through the Jackrabbit-based
+ * application.
+ *
+ * <p>
+ * For an existing {@link Binary} value that implements {@link BinaryDownload},
+ * a read-only URI (see {@link BinaryDownload#getURI(BinaryDownloadOptions)})
+ * can be retrieved and passed to a remote client, such as a browser.
+ *
+ * <h3>Direct Binary Upload</h3>
+ *
+ * This feature enables remote clients to upload binaries directly to a storage
+ * location.
+ *
+ * <p>
+ * Note: When adding binaries already present on the same JVM/server as
+ * the JCR repository, for example because they were generated locally, please
+ * use the regular JCR API {@link ValueFactory#createBinary(InputStream)}
+ * instead. This feature is solely designed for remote clients.
+ *
+ * <p>
+ * The direct binary upload process is split into 3 phases:
+ * <ol>
+ *     <li>
+ *         <b>Initialize</b>: A remote client makes request to the
+ *         Jackrabbit-based application to request an upload, which calls {@link
+ *         #initiateBinaryUpload(long, int)} and returns the resulting {@link
+ *         BinaryUpload instructions} to the remote client.
+ *     </li>
+ *     <li>
+ *         <b>Upload</b>: The remote client performs the actual binary upload
+ *         directly to the binary storage provider. The {@link BinaryUpload}
+ *         returned from the previous call to {@link
+ *         #initiateBinaryUpload(long, int)} contains detailed instructions on
+ *         how to complete the upload successfully.
+ *     </li>
+ *     <li>
+ *         <b>Complete</b>: The remote client notifies the Jackrabbit-based
+ *         application that step 2 is complete. The upload token returned in
+ *         the first step (obtained by calling {@link
+ *         BinaryUpload#getUploadToken()} is passed by the application to {@link
+ *         #completeBinaryUpload(String)}. This will provide the application
+ *         with a regular {@link Binary JCR Binary} that can then be used to
+ *         write JCR content including the binary (such as an nt:file structure)
+ *         and persist it using {@link Session#save}.
+ *     </li>
+ * </ol>
+ */
+@ProviderType
+public interface JackrabbitValueFactory extends ValueFactory {
+
+    /**
+     * Initiate a transaction to upload a binary directly to a storage
+     * location and return {@link BinaryUpload} instructions for a remote client.
+     * Returns {@code null} if the feature is not available.
+     *
+     * <p>
+     * {@link IllegalArgumentException} will be thrown if an upload
+     * cannot be supported for the required parameters, or if the parameters are
+     * otherwise invalid. Each service provider has specific limitations.
+     *
+     * @param maxSize The exact size of the binary to be uploaded or the
+     *                estimated maximum size if the exact size is unknown.
+     *                If the estimation was too small, the transaction
+     *                should be restarted by invoking this method again
+     *                using the correct size.
+     * @param maxURIs The maximum number of upload URIs that the client can
+     *                accept, for example due to message size limitations.
+     *                A value of -1 indicates no limit.
+     *                Upon a successful return, it is ensured that an upload
+     *                of {@code maxSize} can be completed by splitting the
+     *                binary into {@code maxURIs} parts, otherwise
+     *                {@link IllegalArgumentException} will be thrown.
+     *
+     * @return A {@link BinaryUpload} providing the upload instructions,
+     *         or {@code null} if the implementation does not support the direct
+     *         upload feature.
+     *
+     * @throws IllegalArgumentException if the provided arguments are
+     *         invalid or if an upload cannot be completed given the
+     *         provided arguments. For example, if the value of {@code maxSize}
+     *         exceeds the size limits for a single binary upload for the
+     *         implementation or the service provider, or if the value of
+     *         {@code maxSize} divided by {@code maxParts} exceeds the size
+     *         limit for an upload or upload part.
+     *
+     * @throws AccessDeniedException if the session has insufficient
+     *         permission to perform the upload.
+     */
+    @Nullable
+    BinaryUpload initiateBinaryUpload(long maxSize, int maxURIs)
+            throws IllegalArgumentException, AccessDeniedException;
+
+    /**
+     * Complete the transaction of uploading a binary directly to a storage
+     * location and return a {@link Binary} to set as value for a binary
+     * JCR property. The binary is not automatically associated with
+     * any location in the JCR.
+     *
+     * <p>
+     * The client must provide a valid upload token, obtained from
+     * {@link BinaryUpload#getUploadToken()} when this transaction was initialized
+     * using {@link #initiateBinaryUpload(long, int)}.
+     * If the {@code uploadToken} is unreadable or invalid,
+     * an {@link IllegalArgumentException} will be thrown.
+     *
+     * @param uploadToken A String identifying the upload transaction.
+     *
+     * @return The uploaded {@link Binary}, or {@code null} if the
+     *         implementation does not support the direct upload feature.
+     *
+     * @throws IllegalArgumentException if the {@code uploadToken} is invalid or
+     *         does not identify a known binary upload.
+     * @throws RepositoryException if another error occurs.
+     */
+    @Nullable
+    Binary completeBinaryUpload(@NotNull String uploadToken)
+            throws IllegalArgumentException, RepositoryException;
+}

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/binary/BinaryDownload.java

+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.jackrabbit.api.binary;
+
+import java.net.URI;
+
+import javax.jcr.Binary;
+import javax.jcr.RepositoryException;
+
+import org.jetbrains.annotations.Nullable;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * This extension interface provides a mechanism whereby a client can download
+ * a {@link Binary} directly from a storage location.
+ */
+@ProviderType
+public interface BinaryDownload extends Binary {
+    /**
+     *
+     * Returns a URI for downloading this binary directly from the storage location.
+     *
+     * <p>
+     * Using the {@code downloadOptions} parameter, some response headers of the
+     * download request can be overwritten, if supported by the storage provider.
+     * This is necessary to pass information that is only stored in the JCR in
+     * application specific structures, and not reliably available in the binary
+     * storage.
+     *
+     * {@link BinaryDownloadOptions} supports, but is not limited to:
+     * <ul>
+     *     <li>
+     *         {@link BinaryDownloadOptions.BinaryDownloadOptionsBuilder#withMediaType(String) Content-Type media type}:
+     *         typically available in a {@code jcr:mimeType} property
+     *     </li>
+     *     <li>
+     *         {@link BinaryDownloadOptions.BinaryDownloadOptionsBuilder#withCharacterEncoding(String) Content-Type charset}:
+     *         for media types defining a "charset", typically available in a {@code jcr:encoding} property
+     *     </li>
+     *     <li>
+     *         {@link BinaryDownloadOptions.BinaryDownloadOptionsBuilder#withFileName(String) Content-Disposition filename}:
+     *         download file name, typically taken from a JCR node name in the parent hierarchy, such as the nt:file node name
+     *     </li>
+     *     <li>
+     *         {@link BinaryDownloadOptions.BinaryDownloadOptionsBuilder#withDispositionTypeAttachment() Content-Disposition type}:
+     *         whether to show the content inline of a page (inline) or enforce a download/save as (attachment)
+     *     </li>
+     * </ul>
+     *
+     * Specifying {@link BinaryDownloadOptions#DEFAULT} will use mostly empty
+     * defaults, relying on the storage provider attributes for this binary
+     * (that might be empty or different from the information in the JCR).
+     *
+     * <p>
+     * <b>Security considerations:</b>
+     *
+     * <ul>
+     *     <li>
+     *         The URI cannot be shared with other users. It must only be returned to
+     *         authenticated requests corresponding to this session user or trusted system
+     *         components.
+     *     </li>
+     *     <li>
+     *         The URI must not be persisted for later use and will typically be time limited.
+     *     </li>
+     *     <li>
+     *         The URI will only grant access to this particular binary.
+     *     </li>
+     *     <li>
+     *         The client cannot infer any semantics from the URI structure and path names.
+     *         It would typically include a cryptographic signature. Any change to the URI will
+     *         likely result in a failing request.
+     *     </li>
+     *     <li>
+     *         If the client is a browser, consider use of Content-Disposition type = attachment
+     *         for executable media types such as HTML or Javascript if the content cannot be
+     *         trusted.
+     *     </li>
+     * </ul>
+     *
+     * @param downloadOptions
+     *            A {@link BinaryDownloadOptions} instance which is used to
+     *            request specific options on the binary to be downloaded.
+     *            {@link BinaryDownloadOptions#DEFAULT} should be used if the
+     *            caller wishes to accept the storage provider's default
+     *            behavior.
+     * @return A URI for downloading the binary directly, or {@code null} if the
+     *         binary cannot be downloaded directly or if the underlying
+     *         implementation does not support this capability.
+     * @throws RepositoryException if an error occurs trying to locate the
+     *             binary.
+     */
+    @Nullable
+    URI getURI(BinaryDownloadOptions downloadOptions)
+            throws RepositoryException;
+}

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/binary/BinaryDownloadOptions.java

+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.jackrabbit.api.binary;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Specifies the options to be used when obtaining a direct download URI via
+ * {@link BinaryDownload#getURI(BinaryDownloadOptions)}.  Setting these options
+ * allows the caller to instruct the service provider that these options should
+ * be applied to the response to a request made with the URI returned.
+ * <p>
+ * To specify download options, obtain a {@link BinaryDownloadOptionsBuilder}
+ * via the {@link #builder()} method, then specify the options desired and
+ * get the object via {@link BinaryDownloadOptionsBuilder#build()}.
+ * <p>
+ * If no options are needed, use {@link BinaryDownloadOptions#DEFAULT} which
+ * instructs the implementation to use the service provider default behavior.
+ */
+@ProviderType
+public final class BinaryDownloadOptions {
+    private final String mediaType;
+    private final String characterEncoding;
+    private final String fileName;
+    private final String dispositionType;
+
+    private BinaryDownloadOptions(final String mediaType,
+                                  final String characterEncoding,
+                                  final String fileName,
+                                  final String dispositionType) {
+        this.mediaType = mediaType;
+        this.characterEncoding = characterEncoding;
+        this.fileName = fileName;
+        this.dispositionType = dispositionType;
+    }
+
+    /**
+     * Provides a default instance of this class.  Using the default instance
+     * indicates that the caller is willing to accept the service provider
+     * default behavior.
+     */
+    public static final BinaryDownloadOptions DEFAULT =
+            BinaryDownloadOptions.builder().build();
+
+    /**
+     * Returns the internet media type that should be assumed for the binary that is to be
+     * downloaded.  This value should be a valid {@code jcr:mimeType}.  This
+     * value can be set by calling {@link
+     * BinaryDownloadOptionsBuilder#withMediaType(String)} when building an
+     * instance of this class.
+     *
+     * @return A String representation of the internet media type, or {@code null} if no
+     *         type has been specified.
+     * @see <a href="https://docs.adobe.com/content/docs/en/spec/jcr/2.0/3_Repository_Model.html#3.7.11.10%20mix:mimeType">
+     *     JCR 2.0 Repository Model - jcr:mimeType</a>
+     */
+    @Nullable
+    public final String getMediaType() {
+        return mediaType;
+    }
+
+    /**
+     * Returns the character encoding that should be assumed for the binary that
+     * is to be downloaded.  This value should be a valid {@code jcr:encoding}.
+     * It can be set by calling {@link
+     * BinaryDownloadOptionsBuilder#withCharacterEncoding(String)} when building an
+     * instance of this class.
+     *
+     * @return The character encoding, or {@code null} if no
+     *         encoding has been specified.
+     * @see <a href="https://docs.adobe.com/content/docs/en/spec/jcr/2.0/3_Repository_Model.html#3.7.11.10%20mix:mimeType">
+     *     JCR 2.0 Repository Model - jcr:encoding</a>
+     */
+    @Nullable
+    public final String getCharacterEncoding() {
+        return characterEncoding;
+    }
+
+    /**
+     * Returns the filename that should be assumed for the binary that is to be
+     * downloaded.  This value can be set by calling {@link
+     * BinaryDownloadOptionsBuilder#withFileName(String)} when building an
+     * instance of this class.
+     *
+     * @return The file name, or {@code null} if no
+     * file name has been specified.
+     */
+    @Nullable
+    public final String getFileName() {
+        return fileName;
+    }
+
+    /**
+     * Returns the disposition type that should be assumed for the binary that
+     * is to be downloaded.  This value can be set by calling {@link
+     * BinaryDownloadOptionsBuilder#withDispositionTypeInline()} or {@link
+     * BinaryDownloadOptionsBuilder#withDispositionTypeAttachment()} when
+     * building an instance of this class.  The default value of this setting is
+     * "inline".
+     *
+     * @return The disposition type.
+     * @see <a href="https://tools.ietf.org/html/rfc6266#section-4.2">RFC 6266, Section 4.2</a> 
+     */
+    @NotNull
+    public final String getDispositionType() {
+        return dispositionType;
+    }
+
+    /**
+     * Returns a {@link BinaryDownloadOptionsBuilder} instance to be used for
+     * creating an instance of this class.
+     *
+     * @return A builder instance.
+     */
+    @NotNull
+    public static BinaryDownloadOptionsBuilder builder() {
+        return new BinaryDownloadOptionsBuilder();
+    }
+
+    /**
+     * Used to build an instance of {@link BinaryDownloadOptions} with the
+     * options set as desired by the caller.
+     */
+    public static final class BinaryDownloadOptionsBuilder {
+        private String mediaType = null;
+        private String characterEncoding = null;
+        private String fileName = null;
+        private DispositionType dispositionType = DispositionType.INLINE;
+
+        private BinaryDownloadOptionsBuilder() { }
+
+        /**
+         * Sets the internet media type of the {@link BinaryDownloadOptions} object to be
+         * built.  This value should be a valid {@code jcr:mimeType}.
+         * <p>
+         * Calling this method has the effect of instructing the service
+         * provider to set {@code mediaType} as the internet media type
+         * in the {@code Content-Type} header field of the response to a request
+         * issued with a URI obtained by calling {@link
+         * BinaryDownload#getURI(BinaryDownloadOptions)}.  This value can be
+         * later retrieved by calling {@link
+         * BinaryDownloadOptions#getMediaType()} on the instance returned from a
+         * call to {@link #build()}.
+         * <p>
+         * Note that if the internet media type defines a "charset" parameter
+         * (as many textual types do), the caller may also wish to set the
+         * character encoding which is done separately.  See {@link
+         * #withCharacterEncoding(String)}.
+         * <p>
+         * The caller should ensure that the internet media type set is valid; the
+         * implementation does not perform any validation of this setting.
+         * <p>
+         * If no internet media type is provided, no {@code Content-Type} header field will be
+         * specified to the service provider.
+         *
+         * @param mediaType The internet media type.
+         * @return The calling instance.
+         * @see <a href="https://docs.adobe.com/content/docs/en/spec/jcr/2.0/3_Repository_Model.html#3.7.11.10%20mix:mimeType">
+         *     JCR 2.0 Repository Model - jcr:mimeType</a>
+         */
+        @NotNull
+        public BinaryDownloadOptionsBuilder withMediaType(@NotNull String mediaType) {
+            this.mediaType = mediaType;
+            return this;
+        }
+
+        /**
+         * Sets the character encoding of the {@link BinaryDownloadOptions} object to be
+         * built. This value should be a valid {@code jcr:encoding} property value.
+         * <p>
+         * Calling this method has the effect of instructing the service
+         * provider to set {@code characterEncoding} as the "charset" parameter
+         * of the content type in the {@code Content-Type} header field of the
+         * response to a request issued with a URI obtained by calling {@link
+         * BinaryDownload#getURI(BinaryDownloadOptions)}.  This value can be
+         * later retrieved by calling {@link
+         * BinaryDownloadOptions#getCharacterEncoding()} on the instance returned by a
+         * call to {@link #build()}.
+         * <p>
+         * Note that setting the character encoding only makes sense if the internet
+         * media type has also been set, and that media type actually defines a
+         * "charset" parameter. See {@link #withMediaType(String)}.
+         * <p>
+         * The caller should ensure that the proper character encoding has been set for
+         * the internet media type; the implementation does not perform any validation of
+         * these settings.
+         *
+         * @param characterEncoding A String representation of the jcr:encoding.
+         * @return The calling instance.
+         * @see <a href="https://docs.adobe.com/content/docs/en/spec/jcr/2.0/3_Repository_Model.html#3.7.11.10%20mix:mimeType">
+         *     JCR 2.0 Repository Model - jcr:encoding</a>
+         */
+        @NotNull
+        public BinaryDownloadOptionsBuilder withCharacterEncoding(@NotNull String characterEncoding) {
+            this.characterEncoding = characterEncoding;
+            return this;
+        }
+
+        /**
+         * Sets the filename of the {@link BinaryDownloadOptions} object to be
+         * built. This would typically be based on a JCR node name.
+         * <p>
+         * Calling this method has the effect of instructing the service
+         * provider to set {@code fileName} as the filename in the {@code
+         * Content-Disposition} header of the response to a request issued with
+         * a URI obtained by calling {@link
+         * BinaryDownload#getURI(BinaryDownloadOptions)}.  This value can be
+         * later retrieved by calling {@link
+         * BinaryDownloadOptions#getFileName()} on the instance returned by a
+         * call to {@link #build()}.
+         * <p>
+         *
+         * @param fileName The filename.
+         * @return The calling instance.
+         * @see <a href="https://tools.ietf.org/html/rfc6266#section-4.3">RFC 6266, Section 4.3</a> 
+         */
+        @NotNull
+        public BinaryDownloadOptionsBuilder withFileName(@NotNull String fileName) {
+            this.fileName = fileName;
+            return this;
+        }
+
+        /**
+         * Sets the disposition type of the {@link BinaryDownloadOptions} object
+         * to be built to {@code inline}.
+         * <p>
+         * Calling this method has the effect of instructing the service
+         * provider to set the disposition type in the {@code
+         * Content-Disposition} header of the response to {@code inline}.  This
+         * value can be later retrieved by calling {@link
+         * BinaryDownloadOptions#getDispositionType()} on the instance built by
+         * calling {@link #build()}.
+         * <p>
+         * If this value is not set, the default value of {@code inline}
+         * will be used.
+         *
+         * @return The calling instance.
+         */
+        @NotNull
+        public BinaryDownloadOptionsBuilder withDispositionTypeInline() {
+            dispositionType = DispositionType.INLINE;
+            return this;
+        }
+
+        /**
+         * Sets the disposition type of the {@link BinaryDownloadOptions} object
+         * to be built to {@code attachment}.
+         * <p>
+         * Calling this method has the effect of instructing the service
+         * provider to set the disposition type in the {@code
+         * Content-Disposition} header of the response to {@code attachment}.
+         * This value can later be retrieved by calling {@link
+         * BinaryDownloadOptions#getDispositionType()} on the instance built by
+         * calling {@link #build()}.
+         * <p>
+         * If this value is not set, the default value of {@code inline}
+         * will be used.
+         *
+         * @return The calling instance.
+         */
+        @NotNull
+        public BinaryDownloadOptionsBuilder withDispositionTypeAttachment() {
+            dispositionType = DispositionType.ATTACHMENT;
+            return this;
+        }
+
+        /**
+         * Construct a {@link BinaryDownloadOptions} instance with the
+         * properties specified to the builder.
+         *
+         * @return A new {@link BinaryDownloadOptions} instance built with the
+         *         properties specified to the builder.
+         */
+        @NotNull
+        public BinaryDownloadOptions build() {
+            return new BinaryDownloadOptions(mediaType,
+                    characterEncoding,
+                    fileName,
+                    null != dispositionType
+                            ? dispositionType.toString()
+                            : DispositionType.INLINE.toString()
+            );
+        }
+
+        private enum DispositionType {
+            INLINE("inline"),
+            ATTACHMENT("attachment");
+
+            private final String value;
+
+            DispositionType(final String value) {
+                this.value = value;
+            }
+
+            @Override
+            public String toString() {
+                return value;
+            }
+        }
+    }
+}

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/binary/BinaryUpload.java

+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.jackrabbit.api.binary;
+
+import java.net.URI;
+
+import org.apache.jackrabbit.api.JackrabbitValueFactory;
+import org.jetbrains.annotations.NotNull;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Describes uploading a binary through HTTP requests in a single or multiple
+ * parts. This will be returned by
+ * {@link JackrabbitValueFactory#initiateBinaryUpload(long, int)}. A high-level
+ * overview of the process can be found in {@link JackrabbitValueFactory}.
+ *
+ * <p>
+ * Note that although the API allows URI schemes other than "http(s)", the
+ * upload functionality is currently only defined for HTTP.
+ *
+ * <p>
+ * A caller usually needs to pass the information provided by this interface to
+ * a remote client that is in possession of the actual binary, who then has to
+ * upload the binary using HTTP according to the logic described below. A remote
+ * client is expected to support multi-part uploads as per the logic described
+ * below, in case multiple URIs are returned.
+ *
+ * <p>
+ * Once a remote client finishes uploading the binary data, the application must
+ * be notified and must then call
+ * {@link JackrabbitValueFactory#completeBinaryUpload(String)} to complete the
+ * upload. This completion requires the exact upload token obtained from
+ * {@link #getUploadToken()}.
+ *
+ * <h2 id="upload.algorithm">Upload algorithm</h2>
+ *
+ * A remote client will have to follow this algorithm to upload a binary based
+ * on the information provided by this interface.
+ *
+ * <p>
+ * Please be aware that if the size passed to
+ * {@link JackrabbitValueFactory#initiateBinaryUpload(long, int)} was an
+ * estimation, but the actual binary is larger, there is no guarantee the
+ * upload will be possible using all {@link #getUploadURIs()} and the
+ * {@link #getMaxPartSize()}. In such cases, the application should restart the
+ * transaction using the correct size.
+ *
+ * <h3>Variables used</h3>
+ * <ul>
+ *     <li>{@code fileSize}: the actual binary size (must be known at this
+ *     point)</li>
+ *     <li>{@code minPartSize}: the value from {@link #getMinPartSize()}</li>
+ *     <li>{@code maxPartSize}: the value from {@link #getMaxPartSize()}</li>
+ *     <li>{@code numUploadURIs}: the number of entries in {@link
+ *     #getUploadURIs()}</li>
+ *     <li>{@code uploadURIs}: the entries in {@link #getUploadURIs()}</li>
+ *     <li>{@code partSize}: the part size to be used in the upload (to be
+ *     determined in the algorithm)</li>
+ * </ul>
+ *
+ * <h3>Steps</h3>
+ * <ol>
+ *     <li>
+ *         If {@code (fileSize / maxPartSize) > numUploadURIs}, then the
+ *         client cannot proceed and will have to request a new set of URIs
+ *         with the right fileSize as {@code maxSize}
+ *     </li>
+ *     <li>
+ *         If {@code fileSize < minPartSize}, then take the first provided
+ *         upload URI to upload the entire binary, with
+ *         {@code partSize = fileSize}
+ *     </li>
+ *     <li>
+ *         (optional) If the client has more information to optimize, the
+ *         {@code partSize} can be chosen, under the condition that all of these are
+ *         true:
+ *         <ol>
+ *             <li>{@code partSize >= minPartSize}</li>
+ *             <li>{@code partSize <= maxPartSize}
+ *             (unless {@code maxPartSize = -1} meaning unlimited)</li>
+ *             <li>{@code partSize > (fileSize / numUploadURIs)}</li>
+ *         </ol>
+ *     </li>
+ *     <li>
+ *         Otherwise all part URIs are to be used. The {@code partSize}
+ *         to use for all parts except the last would be calculated using:
+ *         <pre>partSize = (fileSize + numUploadURIs - 1) / numUploadURIs</pre>
+ *     </li>
+ *     <li>
+ *         Upload: segment the binary into {@code partSize}, for each segment take the
+ *         next URI from {@code uploadURIs} (strictly in order), proceed with a standard
+ *         HTTP PUT for each, and for the last part use whatever segment size is left
+ *     </li>
+ *     <li>
+ *         If a segment fails during upload, retry (up to a certain timeout)
+ *     </li>
+ *     <li>
+ *         After the upload has finished successfully, notify the application,
+ *         for example through a complete request, passing the {@link
+ *         #getUploadToken() upload token}, and the application will call {@link
+ *         JackrabbitValueFactory#completeBinaryUpload(String)} with the token
+ *     </li>
+ * </ol>
+ *
+ * <h2>Example JSON view</h2>
+ *
+ * A JSON representation of this interface as passed back to a remote client
+ * might look like this:
+ * 
+ * <pre>
+ * {
+ *     "uploadToken": "aaaa-bbbb-cccc-dddd-eeee-ffff-gggg-hhhh",
+ *     "minPartSize": 10485760,
+ *     "maxPartSize": 104857600,
+ *     "uploadURIs": [
+ *         "http://server.com/upload/1",
+ *         "http://server.com/upload/2",
+ *         "http://server.com/upload/3",
+ *         "http://server.com/upload/4"
+ *     ]
+ * }
+ * </pre>
+ */
+@ProviderType
+public interface BinaryUpload {
+    /**
+     * Returns a list of URIs that can be used for uploading binary data
+     * directly to a storage location in one or more parts.
+     *
+     * <p>
+     * Remote clients must support multi-part uploading as per the
+     * <a href="#upload.algorithm">upload algorithm</a> described above. Clients
+     * are not necessarily required to use all of the URIs provided. A client
+     * may choose to use fewer, or even only one of the URIs. However, it must
+     * always ensure the part size is between {@link #getMinPartSize()} and
+     * {@link #getMaxPartSize()}. These can reflect strict limitations of the
+     * storage provider.
+     *
+     * <p>
+     * Regardless of the number of URIs used, they must be consumed in sequence,
+     * without skipping any, and the order of parts the original binary is split
+     * into must correspond exactly with the order of URIs.
+     *
+     * <p>
+     * For example, if a client wishes to upload a binary in three parts and
+     * there are five URIs returned, the client must use the first URI to
+     * upload the first part, the second URI to upload the second part, and
+     * the third URI to upload the third part. The client is not required to
+     * use the fourth and fifth URIs. However, using the second URI to upload
+     * the third part may result in either an upload failure or a corrupted
+     * upload; likewise, skipping the second URI to use subsequent URIs may
+     * result in either an upload failure or a corrupted upload.
+     *
+     * <p>
+     * While the API supports multi-part uploading via multiple upload URIs,
+     * implementations are not required to support multi-part uploading. If the
+     * underlying implementation does not support multi-part uploading, a single
+     * URI will be returned regardless of the size of the data being uploaded.
+     *
+     * <p>
+     * <b>Security considerations:</b>
+     *
+     * <ul>
+     *     <li>
+     *         The URIs cannot be shared with other users. They must only be returned to
+     *         authenticated requests corresponding to this session user or trusted system
+     *         components.
+     *     </li>
+     *     <li>
+     *         The URIs must not be persisted for later use and will typically be time limited.
+     *     </li>
+     *     <li>
+     *         The URIs will only grant access to this particular binary.
+     *     </li>
+     *     <li>
+     *         The client cannot infer any semantics from the URI structure and path names.
+     *         It would typically include a cryptographic signature. Any change to the URIs will
+     *         likely result in a failing request.
+     *     </li>
+     * </ul>
+     *
+     * @return Iterable of URIs that can be used for uploading directly to a
+     *         storage location.
+     */
+    @NotNull
+    Iterable<URI> getUploadURIs();
+
+    /**
+     * Return the smallest possible part size in bytes. If a consumer wants to
+     * choose a custom part size, it cannot be smaller than this value. This
+     * does not apply to the final part. This value will be equal or larger than
+     * zero.
+     *
+     * <p>
+     * Note that the API offers no guarantees that using this minimal part size
+     * is possible with the number of available {@link #getUploadURIs()}. This
+     * might not be the case if the binary is too large. Please refer to the
+     * <a href="#upload.algorithm">upload algorithm</a> for the correct use of
+     * this value.
+     *
+     * @return The smallest part size acceptable for multi-part uploads.
+     */
+    long getMinPartSize();
+
+    /**
+     * Return the largest possible part size in bytes. If a consumer wants to
+     * choose a custom part size, it cannot be larger than this value.
+     * If this returns -1, the maximum is unlimited.
+     *
+     * <p>
+     * The API guarantees that a client can split the binary of the requested
+     * size using this maximum part size and there will be sufficient URIs
+     * available in {@link #getUploadURIs()}. Please refer to the
+     * <a href="#upload.algorithm">upload algorithm</a> for the correct use of
+     * this value.
+     *
+     * @return The maximum part size acceptable for multi-part uploads or -1
+     *         if there is no limit.
+     */
+    long getMaxPartSize();
+
+    /**
+     * Returns a token identifying this upload. This is required to finalize the upload
+     * at the end by calling {@link JackrabbitValueFactory#completeBinaryUpload(String)}.
+     *
+     * <p>
+     * The format of this string is implementation-dependent. Implementations must ensure
+     * that clients cannot guess tokens for existing binaries.
+     *
+     * @return A unique token identifying this upload.
+     */
+    @NotNull
+    String getUploadToken();
+}

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/binary/package-info.java

+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Interfaces related to direct upload/download of binaries.
+ */
+@Version("1.0.0")
+package org.apache.jackrabbit.api.binary;
+
+import org.osgi.annotation.versioning.Version;
\ No newline at end of file

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/jmx/package-info.java

@@ -18,5 +18,5 @@
 /**
  * JMX management interfaces for JCR.
  */
-@aQute.bnd.annotation.Version("2.3.0")
+@org.osgi.annotation.versioning.Version("2.3.0")
 package org.apache.jackrabbit.api.jmx;

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/management/MarkEventListener.java

@@ -26,7 +26,9 @@ public interface MarkEventListener {
 
     /**
      * This method is called before a node is scanned.
+     * 
+     * @param node node to be scanned
      */
-    void beforeScanning(Node n) throws RepositoryException;
+    void beforeScanning(Node node) throws RepositoryException;
 
 }
\ No newline at end of file

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/management/package-info.java

@@ -18,5 +18,5 @@
 /**
  * Interfaces for managing a Jackrabbit repository.
  */
-@aQute.bnd.annotation.Version("2.3.1")
+@org.osgi.annotation.versioning.Version("2.3.1")
 package org.apache.jackrabbit.api.management;

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/package-info.java

@@ -18,5 +18,5 @@
 /**
  * Jackrabbit extensions for JCR observation.
  */
-@aQute.bnd.annotation.Version("2.3.1")
+@org.osgi.annotation.versioning.Version("2.3.1")
 package org.apache.jackrabbit.api.observation;

jackrabbit-api/src/main/java/org/apache/jackrabbit/api/package-info.java

@@ -18,5 +18,5 @@
 /**
  * Jackrabbit extensions for JCR core interfaces
  */
-@aQute.bnd.annotation.Version("2.4")
+@org.osgi.annotation.versioning.Version("2.5.0")
 package org.apache.jackrabbit.api;