Skip to content

Commit d78fa02

Browse files
MrCreosoteMrCreosote
authored
Merge pull request #34 from kbase/dev-gradle_update
Update docs and use jitpack jars
2 parents 7be7234 + 31299da commit d78fa02

File tree

11 files changed

+153
-588
lines changed

11 files changed

+153
-588
lines changed

‎README.md‎

Lines changed: 61 additions & 180 deletions
Original file line numberDiff line numberDiff line change
@@ -1,184 +1,65 @@
1-
Basic java client for the Shock service. Supports node creation, deletion and
2-
retrieval of a subset of node data, streaming file up/download, viewing
3-
ACLs, and limited ACL modification.
4-
5-
Basic Usage
6-
-----------
7-
8-
```java
9-
import java.io.ByteArrayInputStream;
10-
import java.io.ByteArrayOutputStream;
11-
import java.io.InputStream;
12-
import java.net.URL;
13-
import java.nio.charset.StandardCharsets;
14-
import java.util.Arrays;
15-
16-
import us.kbase.auth.AuthConfig;
17-
import us.kbase.auth.AuthToken;
18-
import us.kbase.auth.ConfigurableAuthService;
19-
import us.kbase.shock.client.BasicShockClient;
20-
import us.kbase.shock.client.ShockACL;
21-
import us.kbase.shock.client.ShockACLType;
22-
import us.kbase.shock.client.ShockNode;
23-
24-
public class TryShock {
25-
26-
public static void main(String[] args) throws Exception {
27-
final ConfigurableAuthService auth = new ConfigurableAuthService(new AuthConfig()
28-
.withKBaseAuthServerURL(new URL(
29-
"https://appdev.kbase.us/services/auth/api/legacy/KBase/Sessions/Login")));
30-
final AuthToken t = auth.validateToken(args[0]);
31-
final BasicShockClient c = new BasicShockClient(
32-
new URL("https://appdev.kbase.us/services/shock-api"), t);
33-
System.out.println(c.getShockVersion());
34-
35-
final String s = "You try that around here, young man, and we'll slit your face";
36-
final InputStream is = new ByteArrayInputStream(s.getBytes(StandardCharsets.UTF_8));
37-
38-
final ShockNode sn = c.addNode(is, 61, "myfile", "UTF-8");
39-
System.out.println(sn.getFileInformation());
40-
41-
final ShockNode sn2 = c.getNode(sn.getId());
42-
final ByteArrayOutputStream os = new ByteArrayOutputStream();
43-
sn2.getFile(os);
44-
System.out.println(new String(os.toByteArray(), StandardCharsets.UTF_8));
45-
46-
final ShockACL acl1 = sn2.addToNodeAcl(Arrays.asList("kbasetest2"), ShockACLType.READ);
47-
System.out.println(acl1.getRead());
48-
49-
final ShockACL acl2 = c.getACLs(sn2.getId());
50-
System.out.println(acl2.getRead());
51-
52-
sn2.delete();
53-
}
54-
}
1+
# Blobstore client
2+
3+
This is a basic client for the [Blobstore](https://github.com/kbase/blobstore), which replaced
4+
Shock some years ago but has a mostly compatible API.
5+
6+
The client mostly exists for backwards compatibility purposes. If you're starting a new project
7+
using the blobstore, you'd probably be fine with a REST client like the Java 11+ HTTP client,
8+
the Jersey client, etc.
9+
10+
The client supports node creation, deletion and retrieval of node data,
11+
streaming file up/download, and viewing and modifying ACLs.
12+
13+
## Including the client in your build
14+
15+
See https://jitpack.io/#kbase/shock_java_client for instructions on how to include JitPack
16+
built dependencies in your build.
17+
18+
## JavaDoc
19+
20+
JavaDoc is available at
21+
```
22+
https://javadoc.jitpack.io/com/github/kbase/shock_java_client/<version>/javadoc/
5523
```
56-
57-
Output:
58-
59-
0.9.6
60-
ShockFileInformation [checksum={md5=42568d7a6f0b1d81eb3cc2ff53978f74}, name=myfile, format=UTF-8, size=61]
61-
You try that around here, young man, and we'll slit your face
62-
[ShockUserId [uuid=23bf5737-85c5-4b5d-98dd-d5e9848d8d32, username=kbasetest],
63-
ShockUserId [uuid=0038a5e0-67c2-4ce5-b911-b6873b234788, username=kbasetest2]]
64-
[ShockUserId [uuid=23bf5737-85c5-4b5d-98dd-d5e9848d8d32, username=kbasetest],
65-
ShockUserId [uuid=0038a5e0-67c2-4ce5-b911-b6873b234788, username=kbasetest2]]
66-
67-
68-
See the Javadocs for more information.
69-
70-
Compatibility
71-
-------------
72-
73-
Tested against the KBase fork of Shock 0.9.6.
74-
75-
Build
76-
-----
77-
78-
This documentation assumes the build occurs on Ubuntu 12.04LTS,
79-
but things should work similarly on other distributions. It does **not**
80-
assume that the KBase runtime or `dev_container` are installed.
81-
82-
The build requires:
83-
84-
Java JDK 8+
85-
86-
[Java ant](http://ant.apache.org):
87-
88-
sudo apt-get install ant
89-
90-
Clone the jars and shock_java_client repos:
91-
92-
bareubuntu@bu:~/shockclient$ git clone https://github.com/kbase/jars
93-
Cloning into 'jars'...
94-
remote: Counting objects: 1499, done.
95-
remote: Total 1499 (delta 0), reused 0 (delta 0), pack-reused 1499
96-
Receiving objects: 100% (1499/1499), 60.22 MiB | 2.22 MiB/s, done.
97-
Resolving deltas: 100% (645/645), done.
98-
99-
bareubuntu@bu:~/shockclient$ git clone https://github.com/kbase/shock_java_client
100-
Cloning into 'shock_java_client'...
101-
remote: Counting objects: 572, done.
102-
remote: Total 572 (delta 0), reused 0 (delta 0), pack-reused 572
103-
Receiving objects: 100% (572/572), 97.59 KiB, done.
104-
Resolving deltas: 100% (254/254), done.
105-
106-
Build:
107-
108-
bareubuntu@bu:~/shockclient$ cd shock_java_client/
109-
110-
bareubuntu@bu:~/shockclient/shock_java_client$ make
111-
ant compile -Dcompile.jarfile=shock-client-0.0.15
112-
Buildfile: /home/bareubuntu/shockclient/shock_java_client/build.xml
113-
114-
init:
115-
[mkdir] Created dir: /home/bareubuntu/shockclient/shock_java_client/classes
116-
[mkdir] Created dir: /home/bareubuntu/shockclient/shock_java_client/docs
117-
118-
compile:
119-
[javac] Compiling 25 source files to /home/bareubuntu/shockclient/shock_java_client/classes
120-
[javac] warning: [options] bootstrap class path not set in conjunction with -source 1.6
121-
[javac] 1 warning
122-
[jar] Building jar: /home/bareubuntu/shockclient/shock_java_client/shock-client-0.0.15.jar
123-
[jar] Building jar: /home/bareubuntu/shockclient/shock_java_client/shock-client-0.0.15-sources.jar
124-
125-
BUILD SUCCESSFUL
126-
Total time: 2 seconds
127-
rm -r docs
128-
ant javadoc
129-
Buildfile: /home/bareubuntu/shockclient/shock_java_client/build.xml
130-
131-
init:
132-
[mkdir] Created dir: /home/bareubuntu/shockclient/shock_java_client/docs
133-
134-
javadoc:
135-
[javadoc] Generating Javadoc
136-
[javadoc] Javadoc execution
137-
[javadoc] Creating destination directory: "/home/bareubuntu/shockclient/shock_java_client/docs/javadoc/"
138-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/BasicShockClient.java...
139-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockACL.java...
140-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockACLResponse.java...
141-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockACLType.java...
142-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockData.java...
143-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockFileInformation.java...
144-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockNode.java...
145-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockNodeId.java...
146-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockNodeResponse.java...
147-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockResponse.java...
148-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockUserId.java...
149-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/ShockVersionStamp.java...
150-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/InvalidShockUrlException.java...
151-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockAuthorizationException.java...
152-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockException.java...
153-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockHttpException.java...
154-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockIllegalShareException.java...
155-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockIllegalUnshareException.java...
156-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockNoFileException.java...
157-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockNoNodeException.java...
158-
[javadoc] Loading source file /home/bareubuntu/shockclient/shock_java_client/src/us/kbase/shock/client/exceptions/ShockNodeDeletedException.java...
159-
[javadoc] Constructing Javadoc information...
160-
[javadoc] Standard Doclet version 1.7.0_91
161-
[javadoc] Building tree for all the packages and classes...
162-
[javadoc] Building index for all the packages and classes...
163-
[javadoc] Building index for all classes...
164-
165-
BUILD SUCCESSFUL
166-
Total time: 4 seconds
167-
168-
bareubuntu@bu:~/shockclient/shock_java_client$ ls
169-
build.xml docs RELEASE_NOTES.md
170-
classes internal shock-client-0.0.15.jar
171-
COMMANDS LICENSE.md shock-client-0.0.15-sources.jar
172-
DEPENDENCIES Makefile src
173-
deploy.cfg README.md test
174-
175-
bareubuntu@bu:~/shockclient/shock_java_client$ ls docs/
176-
javadoc
177-
178-
Known issues
179-
------------
180-
181-
- If a client is created such that it trusts self-signed certificates, all
24+
25+
For example:
26+
27+
https://javadoc.jitpack.io/com/github/kbase/shock_java_client/0.2.0/javadoc/
28+
29+
30+
## Basic Usage
31+
32+
See the [TryShock](src/test/java/us/kbase/test/shock/client/TryShock.java) example.
33+
34+
## Development
35+
36+
### Adding and releasing code
37+
38+
* Adding code
39+
* All code additions and updates must be made as pull requests directed at the develop branch.
40+
* All tests must pass and all new code must be covered by tests.
41+
* All new code must be documented appropriately
42+
* Javadoc
43+
* General documentation if appropriate
44+
* Release notes
45+
* Releases
46+
* The main branch is the stable branch. Releases are made from the develop branch to the main
47+
branch.
48+
* Tag the version in git and github.
49+
* Create a github release.
50+
* Check that the javadoc is appropriately built on JitPack.
51+
52+
### Testing
53+
54+
Copy `test.cfg.example` to `test.cfg` and fill it in appropriately. Then:
55+
56+
```
57+
./gradlew test
58+
```
59+
60+
## Known issues
61+
62+
* If a client is created such that it trusts self-signed certificates, all
18263
future clients will also trust all SSCs regardless of the constructor
18364
arguments. Similarly, creation of a standard client means that any new
18465
clients will not trust SSCs.

0 commit comments

Comments
 (0)