Add support for creating Freezer Manager freezer hierarchies via StorageController APIs (#36)

## version 3.1.0
*Released*: 20 September 2022
* Add support for creating Freezer Manager freezer hierarchies via StorageController APIs (earliest compatible LabKey Server version: 22.10.0)
  * CreateCommand, UpdateCommand, DeleteCommand
* Restore proactive authentication behavior. A change in v3.0.0 caused some invocations of `@NoPermissionsRequired`
  actions (e.g., `GetContainersCommand`) to use guest credentials instead of the configured user credentials. The library
  now always authenticates using the configured credentials, matching pre-v3.0.0 behavior.

Author: cnathe

labkey-client-api/CHANGELOG.md

@@ -1,8 +1,17 @@
 # The LabKey Remote API Library for Java - Change Log
 
+## version 3.1.0
+*Released*: 20 September 2022
+* Add support for creating Freezer Manager freezer hierarchies via StorageController APIs (earliest compatible LabKey Server version: 22.10.0)
+  * CreateCommand, UpdateCommand, DeleteCommand
+* Restore proactive authentication behavior. A change in v3.0.0 caused some invocations of `@NoPermissionsRequired`
+  actions (e.g., `GetContainersCommand`) to use guest credentials instead of the configured user credentials. The library
+  now always authenticates using the configured credentials, matching pre-v3.0.0 behavior.
+
 ## version 3.0.0
 *Released*: 14 September 2022
 * Migrate internal HTTP handling to use Apache HttpClient 5.1.x
+* Migrate from preemptive to challenge-response Basic authentication 
 * Switch `StopImpersonatingCommand` to disable redirects (mimicking previous behavior)
 * Add `Connection.stopImpersonating()` and deprecate `stopImpersonate()`
 * Remove deprecated methods:

labkey-client-api/README.md

@@ -21,7 +21,7 @@ compatibility with LabKey Server versions.
 ### Dependency Declaration
 To declare a dependency on this jar file, you can use the following in Gradle
 
-```compile(group: 'org.labkey.api', name: 'labkey-client-api', version: '1.2.0')```
+```compile(group: 'org.labkey.api', name: 'labkey-client-api', version: '3.1.0')```
 
 If using the LabKey Gradle plugins and building a LabKey module, it is best to 
 use this utility method instead to facilitate testing of any local changes to
@@ -59,7 +59,7 @@ When your feature development is done, you should:
 
 - Update the version number in the `build.gradle` file to the next logical SNAPSHOT version corresponding to your changes
 following the [SemVer](https://semver.org/) guidelines.  Make sure this is a SNAPSHOT version (e.g., `1.2.3-SNAPSHOT`).
-- Update the [change log](CHANGELOG.md) to document what has changed.  You can leave the release date and version alone at this 
+- Update the [change log](CHANGELOG.md) to document what has changed. You can leave the release date and version alone at this 
 point; they will get updated when the next release is published.
 - **TBD** Run tests using your SNAPSHOT version of the tests
 - Merge your branch into develop if appropriate tests are passing.

labkey-client-api/build.gradle

@@ -57,7 +57,7 @@ repositories {
 
 group "org.labkey.api"
 
-version "3.1.0-SNAPSHOT"
+version "3.2.0-SNAPSHOT"
 
 dependencies {
     api ("com.googlecode.json-simple:json-simple:${jsonSimpleVersion}")

labkey-client-api/src/org/labkey/remoteapi/Command.java

@@ -441,18 +441,12 @@ protected ResponseType createResponse(String text, int status, String contentTyp
      * @throws CommandException Thrown if there is a problem encoding or parsing the URL
      * @throws URISyntaxException Thrown if there is a problem parsing the base URL in the connection.
      */
+
+    // TODO: For next major release, remove CommandException from throws list
     protected HttpUriRequest getHttpRequest(Connection connection, String folderPath) throws CommandException, URISyntaxException
     {
-// TODO        (Dave 11/11/14 -- as far as I can tell the default of the AuthSchemes is to automatically handle challenges
-//        method.setDoAuthentication(true);
-
-        // NOTE: Fairly sure that the "unescaped" comment below is obsolete
-        // TODO: Combine getActionUrl() and addParameters() into a single method
-        //construct a URI from the results of the getActionUrl method
-        //note that this method returns an unescaped URL, so pass
-        //false for the second parameter to escape it
-        URI uri = getActionUrl(connection, folderPath);
-        uri = addParameters(uri);
+        //construct a URI from connection base URI, folder path, and current parameters
+        URI uri = createURI(connection, folderPath);
 
         return createRequest(uri);
     }
@@ -469,17 +463,14 @@ protected HttpUriRequest createRequest(URI uri)
     }
 
     /**
-     * Returns the portion of the URL before the query string for this command.
-     * <p>
-     * Note that the URL returned should <em>not</em> be encoded, as the calling function will encode it.
-     * <p>
-     * For example: "http://localhost:8080/labkey/MyProject/MyFolder/selectRows.api"
+     * Returns a full URI for this Command, including base URI, folder path, and query string.
+     *
      * @param connection The connection to use.
      * @param folderPath The folder path to use.
-     * @return The URL
+     * @return The URI
      * @throws URISyntaxException if the uri constructed from the parameters is malformed
      */
-    private URI getActionUrl(Connection connection, String folderPath) throws URISyntaxException
+    private URI createURI(Connection connection, String folderPath) throws URISyntaxException
     {
         URI uri = connection.getBaseURI();
 
@@ -508,52 +499,34 @@ private URI getActionUrl(Connection connection, String folderPath) throws URISyn
         if (!actionName.endsWith(".api"))
             path.append(".api");
 
-        return new URIBuilder(uri).setPath(path.toString()).build();
-    }
+        URIBuilder builder = new URIBuilder(uri).setPath(path.toString());
 
-    /**
-     * Adds all parameters to the passed URI
-     * <p>
-     * @return The URI with parameters added
-     * @throws CommandException Thrown if there is a problem building the URI
-     */
-    protected URI addParameters(URI uri) throws CommandException, URISyntaxException
-    {
         Map<String, Object> params = getParameters();
 
         //add the required version if it's > 0
         if (getRequiredVersion() > 0)
             params.put(CommonParameters.apiVersion.name(), getRequiredVersion());
 
-        if (params.isEmpty())
-            return uri;
-
-        URIBuilder builder = new URIBuilder(uri);
-
-        for (String name : params.keySet())
+        if (!params.isEmpty())
         {
-            Object value = params.get(name);
-            if (value instanceof Collection<?> col)
+            for (String name : params.keySet())
             {
-                for (Object o : col)
+                Object value = params.get(name);
+                if (value instanceof Collection<?> col)
                 {
-                    addParameter(builder, name, o);
+                    for (Object o : col)
+                    {
+                        addParameter(builder, name, o);
+                    }
+                }
+                else
+                {
+                    addParameter(builder, name, value);
                 }
-            }
-            else
-            {
-                addParameter(builder, name, value);
             }
         }
 
-        try
-        {
-            return builder.build();
-        }
-        catch (URISyntaxException e)
-        {
-            throw new CommandException(e.getMessage());
-        }
+        return builder.build();
     }
 
     private void addParameter(URIBuilder builder, String name, Object value)
@@ -592,7 +565,7 @@ public double getRequiredVersion()
      * Sets the required version number for this API call.
      * By default, the required version is 8.3, meaning that
      * this call requires LabKey Server version 8.3 or higher.
-     * Set this to a higher number to required a later
+     * Set this to a higher number to require a later
      * version of the server.
      * @param requiredVersion The new required version
      */
@@ -606,8 +579,9 @@ public void setRequiredVersion(double requiredVersion)
      * to copy their own data members   
      * @return A copy of this object
      */
+    // TODO: For next major release, genericize this return value (Command<ResponseType>)
     public Command copy()
     {
-        return new Command(this);
+        return new Command<>(this);
     }
 }

labkey-client-api/src/org/labkey/remoteapi/CommandResponse.java

@@ -132,7 +132,7 @@ public Command getSourceCommand()
      * @return The parsed data as a property map.
      */
     @SuppressWarnings("unchecked")
-    public Map<String,Object> getParsedData()
+    public Map<String, Object> getParsedData()
     {
         if(null == _data && null != getText()
                 && null != _contentType && _contentType.contains(Command.CONTENT_TYPE_JSON))
@@ -174,7 +174,7 @@ public <T> T getProperty(String path)
      * @return The property value, or null if not found.
      */
     @SuppressWarnings("unchecked")
-    protected <T> T getProperty(String[] path, int pathIndex, Map<String,Object> parent)
+    protected <T> T getProperty(String[] path, int pathIndex, Map<String, Object> parent)
     {
         if(null == parent)
             return null;
@@ -206,7 +206,7 @@ protected <T> T getProperty(String[] path, int pathIndex, Map<String,Object> par
         {
             //recurse if prop is non-null and instance of map
             return (null != prop && prop instanceof Map)
-                ? (T)getProperty(path, pathIndex + 1, (Map<String,Object>)prop)
+                ? (T)getProperty(path, pathIndex + 1, (Map<String, Object>)prop)
                 : null;
         }
     }

labkey-client-api/src/org/labkey/remoteapi/Connection.java

@@ -38,7 +38,6 @@
 import org.labkey.remoteapi.security.ImpersonateUserCommand;
 import org.labkey.remoteapi.security.LogoutCommand;
 import org.labkey.remoteapi.security.StopImpersonatingCommand;
-import org.labkey.remoteapi.security.WhoAmICommand;
 
 import java.io.IOException;
 import java.net.URI;
@@ -120,6 +119,7 @@ public class Connection
     private Integer _proxyPort;
     private String _csrf;
     private String _sessionId;
+    private boolean _firstRequest = true;
 
     // The user email when impersonating a user
     private String _impersonateUser;
@@ -278,19 +278,19 @@ private HttpClientConnectionManager getSelfSignedConnectionManager()
     }
 
     /**
-     * If necessary, prime the Connection for non-GET requests.
-     * Executes a dummy command to trigger authentication and populate CSRF and session info.
+     * If first request, prime the Connection by forcing authentication and populating CSRF and session info.
      * @param request HttpRequest that is about to be executed
      */
     protected void beforeExecute(HttpRequest request)
     {
-        if (null == _csrf &&
-                request instanceof HttpUriRequestBase && !"GET".equals(request.getMethod()))
+        if (_firstRequest)
         {
-            // make a request to get a JSESSIONID
+            // Make an initial request to ensure login (especially important when invoking @RequiresNoPermission actions),
+            // get a JSESSIONID, and get a CSRF token
             try
             {
-                new WhoAmICommand().execute(this, "/");
+                _firstRequest = false;
+                ensureAuthenticated();
             }
             catch (Exception ignored)
             {
@@ -322,6 +322,7 @@ protected void afterExecute()
      * @throws IOException if there is an IO problem executing the command to ensure login
      * @throws CommandException if the server returned a non-success status code.
      */
+    // TODO: For next major release, stop returning CloseableHttpClient?
     public CloseableHttpClient ensureAuthenticated() throws IOException, CommandException
     {
         EnsureLoginCommand command = new EnsureLoginCommand();
@@ -335,6 +336,7 @@ public CloseableHttpClient ensureAuthenticated() throws IOException, CommandExce
      * @throws IOException if there is an IO problem executing the command to ensure logout
      * @throws CommandException if the server returned a non-success status code.
      */
+    // TODO: For next major release, stop returning CloseableHttpClient?
     public CloseableHttpClient logout() throws IOException, CommandException
     {
         LogoutCommand command = new LogoutCommand();
@@ -492,7 +494,7 @@ public boolean isAcceptSelfSignedCerts()
     }
 
     /**
-     * Sets the accept self-signed certificates option. Set to false
+     * Sets the accept-self-signed certificates option. Set to false
      * to disable automatic acceptance of self-signed SSL certificates
      * when using HTTPS.
      * NOTE: Changing this setting will force the underlying http client to be recreated.
@@ -502,7 +504,6 @@ public boolean isAcceptSelfSignedCerts()
      */
     public Connection setAcceptSelfSignedCerts(boolean acceptSelfSignedCerts)
     {
-        // Handled in getHttpClient using 4.3.x approach documented here http://stackoverflow.com/questions/19517538/ignoring-ssl-certificate-in-apache-httpclient-4-3
         _acceptSelfSignedCerts = acceptSelfSignedCerts;
         _client = null;
         return this;

labkey-client-api/src/org/labkey/remoteapi/PostCommand.java

@@ -61,7 +61,7 @@ public PostCommand(String controllerName, String actionName)
         super(controllerName, actionName);
     }
 
-    public PostCommand(PostCommand source)
+    public PostCommand(PostCommand<ResponseType> source)
     {
         super(source);
         if (null != source.getJsonObject())
@@ -120,6 +120,6 @@ protected HttpUriRequest createRequest(URI uri)
     @Override
     public PostCommand copy()
     {
-        return new PostCommand(this);
+        return new PostCommand<>(this);
     }
 }

labkey-client-api/src/org/labkey/remoteapi/assay/AssayListCommand.java

@@ -117,6 +117,7 @@ public void setId(Integer id)
         _id = id;
     }
 
+    @Override
     protected AssayListResponse createResponse(String text, int status, String contentType, JSONObject json)
     {
         return new AssayListResponse(text, status, contentType, json, this.copy());
@@ -134,9 +135,10 @@ public JSONObject getJsonObject()
         return obj;
     }
 
+    @Override
     public Map<String, Object> getParameters()
     {
-        Map<String,Object> params = new HashMap<String,Object>();
+        Map<String, Object> params = new HashMap<>();
         if(null != getName())
             params.put("name", getName());
         if(null != getType())

labkey-client-api/src/org/labkey/remoteapi/assay/AssayListResponse.java

@@ -15,8 +15,8 @@
  */
 package org.labkey.remoteapi.assay;
 
-import org.labkey.remoteapi.CommandResponse;
 import org.json.simple.JSONObject;
+import org.labkey.remoteapi.CommandResponse;
 
 import java.util.List;
 import java.util.Map;
@@ -52,7 +52,7 @@ public AssayListResponse(String text, int statusCode, String contentType, JSONOb
      * about the particular assay definition.
      * @return The list of definitions.
      */
-    public List<Map<String,Object>> getDefinitions()
+    public List<Map<String, Object>> getDefinitions()
     {
         return getProperty("definitions");
     }
@@ -62,7 +62,7 @@ public List<Map<String,Object>> getDefinitions()
      * @param name The name of the assay definition to find.
      * @return The assay definition or null if not found.
      */
-    public Map<String,Object> getDefinition(String name)
+    public Map<String, Object> getDefinition(String name)
     {
         return findObject(getDefinitions(), "name", name);
     }
@@ -72,7 +72,7 @@ public Map<String,Object> getDefinition(String name)
      * @param id The id of the assay definition to find.
      * @return The assay definition or null if not found.
      */
-    public Map<String,Object> getDefinition(int id)
+    public Map<String, Object> getDefinition(int id)
     {
         return findObject(getDefinitions(), "id", String.valueOf(id));
     }

labkey-client-api/src/org/labkey/remoteapi/assay/Batch.java

@@ -27,7 +27,7 @@
 */
 public class Batch extends ExpObject
 {
-    private List<Run> _runs = new ArrayList<Run>();
+    private List<Run> _runs = new ArrayList<>();
 
     public Batch()
     {

labkey-client-api/src/org/labkey/remoteapi/assay/GetProtocolCommand.java

@@ -34,7 +34,7 @@ public GetProtocolCommand(long protocolId, boolean copy)
     @Override
     public Map<String, Object> getParameters()
     {
-        Map<String,Object> params = new HashMap<>();
+        Map<String, Object> params = new HashMap<>();
         if (_protocolId != null)
         {
             params.put("protocolId", _protocolId);

labkey-client-api/src/org/labkey/remoteapi/assay/Run.java

@@ -30,8 +30,8 @@
 public class Run extends ExpObject
 {
     private String _comment;
-    private List<Data> _dataInputs = new ArrayList<Data>();
-    private List<Data> _dataOutputs = new ArrayList<Data>();
+    private List<Data> _dataInputs = new ArrayList<>();
+    private List<Data> _dataOutputs = new ArrayList<>();
     private List<Material> _materialInputs = new ArrayList<>();
     private List<Material> _materialOutputs = new ArrayList<>();
     private String _lsid;

labkey-client-api/src/org/labkey/remoteapi/assay/nab/NAbRunsCommand.java

@@ -64,14 +64,16 @@ public NAbRunsCommand(NAbRunsCommand source)
         _calculateNeut = source._calculateNeut;
     }
 
+    @Override
     protected NAbRunsResponse createResponse(String text, int status, String contentType, JSONObject json)
     {
         return new NAbRunsResponse(text, status, contentType, json, this.copy());
     }
 
+    @Override
     public Map<String, Object> getParameters()
     {
-        Map<String,Object> params = super.getParameters();
+        Map<String, Object> params = super.getParameters();
 
         if (null != getAssayName())
             params.put("assayName", getAssayName());