Skip to content

Commit 50660c9

Browse files
acoburntimea-solid
acoburn
and
timea-solid
authored
JCL-73: Reorganize, rework high-level documentation (#326)
 Co-authored-by: Timea <4144203+timea-solid@users.noreply.github.com>
1 parent 6bb76c4 commit 50660c9

9 files changed

Lines changed: 536 additions & 346 deletions

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The Inrupt Java Client Libraries provide highly flexible, simple components that
88

99
## Using the libraries as a dependency in your own projects
1010

11-
To use the Inrupt Java Client Libraries in your projects make sure to visit the [Set Up page](https://inrupt.github.io/solid-client-java/setUp.html) of the documentation.
11+
To use the Inrupt Java Client Libraries in your projects make sure to visit the [Getting Started page](https://inrupt.github.io/solid-client-java/getting-started.html) of the documentation.
1212

1313
Next we will document how to use this repository locally.
1414

@@ -70,4 +70,4 @@ forum is a good place to meet the rest of the community.
7070

7171
## License
7272

73-
MIT © [Inrupt](https://inrupt.com)
73+
MIT © [Inrupt](https://inrupt.com)

‎src/site/apt/data-modeling.apt.vm‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
Data Modeling
2+
3+
The high-level <<<SolidClient>>> and <<<SolidSyncClient>>> make it easy to bind your Java objects to RDF-based Solid resources. This guide will help you structure your class definitions to make this possible.
4+
5+
* What you will need
6+
7+
* About 15 minutes
8+
9+
* Your favorite text editor or IDE
10+
11+
* Java 11 or later
12+
13+
* Maven 3.5 or later
14+
15+
* How to complete
16+
17+
The solution involves creating a wrapper class so that your class can act not only as an RDF Graph
18+
but also as a domain-specific type.
19+
20+
* 1. Subclass the Resource type
21+
22+
The first step involves ensuring that your class extends the <<<com.inrupt.client.Resource>>> class.
23+
Afterwards, consider the methods you expect in your class.
24+
25+
+---
26+
public class Playlist extends Resource {
27+
28+
public Playlist(URI identifier, Dataset dataset) {
29+
super(identifier, dataset);
30+
}
31+
32+
public String getTitle() {
33+
...
34+
}
35+
36+
public void setTitle(String title) {
37+
...
38+
}
39+
40+
public Set<URI> getSongs() {
41+
...
42+
}
43+
44+
public void addSong(URI song) {
45+
...
46+
}
47+
}
48+
+---
49+
50+
51+
* 2. Create the wrapper node
52+
53+
Next, you will create an inner class that binds the data between RDF and your class.
54+
55+
+---
56+
public class Playlist extends Resource {
57+
58+
...
59+
60+
static IRI DC_TITLE = rdf.createIRI("http://purl.org/dc/terms/title");
61+
static IRI EX_SONG = rdf.createIRI("http://music.example/song");
62+
63+
static class Node extends WrapperIRI {
64+
Node(RDFTerm original, Graph graph) {
65+
super(original, graph);
66+
}
67+
68+
String getTitle() {
69+
return anyOrNull(DC_TITLE, ValueMappings::literalAsString);
70+
}
71+
72+
void setTitle(String value) {
73+
overwriteNullable(DC_TITLE, value, TermMappings::asStringLiteral);
74+
}
75+
76+
Set<URI> getSongs() {
77+
return objects(EX_SONG, TermMappings::asIri, ValueMappings::iriAsUri);
78+
}
79+
80+
void addSong(URI song) {
81+
add(EX_SONG, song, TermMappings::asIri);
82+
}
83+
}
84+
}
85+
+---
86+
87+
Your inner class (<<<Node>>> in this example) will have access to a variety of functions
88+
to aid in mapping between the underlying RDF Graph and your Java type. {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/WrapperBlankNodeOrIRI.html}These methods}} are summarized in the <<<inrupt-rdf-wrapping-commons>>> Javadocs.
89+
90+
Similarly, the built-in {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/TermMappings.html}TermMappings}}
91+
and {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/ValueMappings.html}ValueMappings}}
92+
are described in the {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/package-summary.html}Javadocs}} for the <<<inrupt-rdf-wrapping-commons>>> library.
93+
94+
* 3. Connect your public methods to the wrapper node
95+
96+
Now you are ready to link your public methods to the methods from your inner class.
97+
98+
+---
99+
public class Playlist extends Resource {
100+
101+
private Node subject;
102+
103+
public Playlist(URI identifier, Dataset dataset) {
104+
super(identifier, dataset);
105+
106+
subject = new Node(rdf.createIRI(identifier.toString()), dataset.getGraph());
107+
}
108+
109+
public String getTitle() {
110+
return subject.getTitle();
111+
}
112+
113+
public void setTitle(String title) {
114+
subject.setTitle(title);
115+
}
116+
117+
public Set<URI> getSongs() {
118+
return subject.getSongs();
119+
}
120+
121+
public void addSong(URI song) {
122+
subject.addSong(song);
123+
}
124+
125+
...
126+
}
127+
+---
128+
129+
* 4. Use your class in the high-level client
130+
131+
Now, you can use your class with the high-level Solid client, mapping data seamlessly between your
132+
Java application and an RDF resource.
133+
134+
+---
135+
public class MyApplication {
136+
137+
public void run() {
138+
Session session = OpenIdConnect.ofClientCredentials(issuer, clientId, clientSecret, "client_secret_basic");
139+
SolidSyncClient client = SolidSyncClient.getClient().session(session);
140+
141+
URI uri = URI.create("https://storage.example/playlists/910b509c-1ca5-4d6a-a093-377e8e1b390e");
142+
try (Playlist playlist = client.read(uri, Playlist.class)) {
143+
System.out.println(playlist.getTitle());
144+
145+
// Add a new song to the playlist
146+
playlist.addSong(song);
147+
148+
// Update the playlist in your storage
149+
client.update(playlist);
150+
}
151+
}
152+
}
153+
+---
154+

‎src/site/apt/getting-started.apt.vm‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Getting Started With Inrupt's Java Client Libraries
2+
3+
This guide will help you set up a Java project using Maven. The project contains all the necessary components to begin building a Solid application.
4+
5+
* What you will need
6+
7+
* About 15 minutes
8+
9+
* Your favorite text editor or IDE
10+
11+
* Java 11 or later
12+
13+
* Maven 3.5 or later
14+
15+
* How to complete
16+
17+
First, issue the following command:
18+
19+
-----------------
20+
$ mvn archetype:generate \
21+
-DarchetypeGroupId=com.inrupt \
22+
-DarchetypeArtifactId=inrupt-client-archetype-java
23+
-----------------
24+
25+
You will be prompted for a <<<groupId>>> value (e.g. <<<com.example>>>) and an <<<artifactId>>> value (e.g. <<<sample-project>>>).
26+
27+
Next, you will be able to find your new project in your current working directory.
28+
29+
To build this new project, issue the following commands:
30+
31+
-----------------
32+
$ cd sample-project
33+
$ mvn install
34+
-----------------
35+
36+
* Next steps
37+
38+
Your project will be configured to use a recommended collection of dependencies and provides a simple starting point for
39+
building a Solid Application.
40+
41+
Next, you will need to consider whether to use a synchronous or asynchronous client for your application, as described in the {{{./usage-examples.html}usage examples}}.

‎src/site/apt/gettingStarted.apt.vm‎

Lines changed: 0 additions & 122 deletions
This file was deleted.

0 commit comments

Comments
 (0)