Arvados

Comments for revision 8ee3fe6

1. "mvn clean package" fails when running tests because I didn't have ARVADOS_API_TOKEN and ARVADOS_API_HOST set up. It should either run the API server in test mode and run the tests against it locally, or it should skip the tests entirely if those environment variables are not available.
2. The tests make changes to the the database, such as calling users.create. This is definitely something that needs to run against a test server, so as to avoid running against a production server and creating junk data.
3. Code requires ARVADOS_API_HOST_INSECURE but doesn't do anything with it. ARVADOS_API_HOST_INSECURE is not required, it should not fail if it is missing. The purpose of this environment variable is to signal whether it is allowed to accept self-signed SSL certificates. If the variable is not set, it should reject self-signed certificates.
4. Jar file should have "arvados" somewhere in the name, e.g. arvados-sdk-1.0.jar
5. Running "java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados" with no arguments prints an exception stack trace.
6. Could we wrap "java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados" with a small script?
7. ArvadosSDKJavaUser should have "example" in the name to make it more obvious that it is an example, e.g. ArvadosSDKExample
8. org.arvados.sdk.java.Arvados constructor should take 'apiVersion', and assume "arvados" to construct the /arvados/v1 prefix
9. org.arvados.sdk.java.Arvados.call() is very verbose. Change call() so that it takes the 'parameters' HashMap directly, instead of parsing out the list. Accept nested HashMap, List, String and numeric parameters and ensure they are serialized to JSON properly. It should verify that the parameters are compatible with the discovery document, and required parameters are present.
10. Successful responses from the server should be parsed as JSON, and return a Map to the caller.
11. POST methods should not require that the payload come from a file. The caller should be able to provide a buffer.
12. I would like examples of more complex API calls with optional parameters and nested JSON parameters, for example index queries with filters.
13. Example API documentation that the user will refer to: http://doc.arvados.org/api/methods/pipeline_templates.html
14. Add a link to http://doc.arvados.org/api/index.html in README
15. Contents of README should eventually migrate into its own page on http://doc.arvados.org/sdk/index.html

1. doc/sdk/java/index.html.textile.liquid
   • URL to "maven-in-five-minutes.html" should be an actual link.
   • Link to user/reference/api-tokens.html instead of re-explaining the Arvados environment variables
   • Provide a link or some other information about the "m2eclipse" plugin
2. Arvados.java
   • "hostInsecure" parameter of constructor should be a boolean, not a String
3. ArvadosSDKJavaExample.java
   • Please note that ARVADOS_API_HOST_INSECURE should only be set during development, add some text so as not to imply that it is required.
   • Is there an easy way to pretty-print the 'response' Map object?
   • The comments should explain a little bit more about what is going on, for example the first "arv.call()" should document each parameter and what is expected to happen.

(In-person comments)

ArvadosSDKJavaExample repeats the "print each entry in a map" code block three times, should be refactored.

ArvadosSDKJavaExampleWithPrompt would be more useful as a simple java version of the 'arv' command-line. Alternately, it could use the discovery document to list out the acceptable values for each of the resource, method, parameters prompts.