acoburn · Mar 3, 2023 · Feb 27, 2023 · Mar 3, 2023 · Mar 3, 2023 · Mar 3, 2023
@@ -8,7 +8,7 @@ The Inrupt Java Client Libraries provide highly flexible, simple components that
 
 ## Using the libraries as a dependency in your own projects
 
-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.
+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.
 
 Next we will document how to use this repository locally.
 
@@ -70,4 +70,4 @@ forum is a good place to meet the rest of the community.
 
 ## License
 
-MIT © [Inrupt](https://inrupt.com)
+MIT © [Inrupt](https://inrupt.com)
@@ -0,0 +1,154 @@
+Data Modeling
+
+    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.
+
+* What you will need
+
+    * About 15 minutes
+
+    * Your favorite text editor or IDE
+
+    * Java 11 or later
+
+    * Maven 3.5 or later
+
+* How to complete
+
+    The solution involves creating a wrapper class so that your class can act not only as an RDF Graph
+    but also as a domain-specific type.
+
+* 1. Subclass the Resource type
+
+    The first step involves ensuring that your class extends the <<<com.inrupt.client.Resource>>> class.
+    Afterwards, consider the methods you expect in your class.
+
++---
+public class Playlist extends Resource {
+
+    public Playlist(URI identifier, Dataset dataset) {
+        super(identifier, dataset);
+    }
+
+    public String getTitle() {
+        ...
+    }
+
+    public void setTitle(String title) {
+        ...
+    }
+
+    public Set<URI> getSongs() {
+        ...
+    }
+
+    public void addSong(URI song) {
+        ...
+    }
+}
++---
+
+
+* 2. Create the wrapper node
+
+    Next, you will create an inner class that binds the data between RDF and your class.
+
++---
+public class Playlist extends Resource {
+
+    ...
+
+    static IRI DC_TITLE = rdf.createIRI("http://purl.org/dc/terms/title");
+    static IRI EX_SONG = rdf.createIRI("http://music.example/song");
+
+    static class Node extends WrapperIRI {
+        Node(RDFTerm original, Graph graph) {
+            super(original, graph);
+        }
+
+        String getTitle() {
+            return anyOrNull(DC_TITLE, ValueMappings::literalAsString);
+        }
+
+        void setTitle(String value) {
+            overwriteNullable(DC_TITLE, value, TermMappings::asStringLiteral);
+        }
+
+        Set<URI> getSongs() {
+            return objects(EX_SONG, TermMappings::asIri, ValueMappings::iriAsUri);
+        }
+
+        void addSong(URI song) {
+            add(EX_SONG, song, TermMappings::asIri);
+        }
+    }
+}
++---
+
+    Your inner class (<<<Node>>> in this example) will have access to a variety of functions
+    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.
+
+    Similarly, the built-in {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/TermMappings.html}TermMappings}}
+    and {{{https://javadoc.io/doc/com.inrupt/inrupt-rdf-wrapping-commons/latest/com/inrupt/rdf/wrapping/commons/ValueMappings.html}ValueMappings}}
+    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.
+
+* 3. Connect your public methods to the wrapper node
+
+    Now you are ready to link your public methods to the methods from your inner class.
+
++---
+public class Playlist extends Resource {
+
+    private Node subject;
+
+    public Playlist(URI identifier, Dataset dataset) {
+        super(identifier, dataset);
+
+        subject = new Node(rdf.createIRI(identifier.toString()), dataset.getGraph());
+    }
+
+    public String getTitle() {
+        return subject.getTitle();
+    }
+
+    public void setTitle(String title) {
+        subject.setTitle(title);
+    }
+
+    public Set<URI> getSongs() {
+        return subject.getSongs();
+    }
+
+    public void addSong(URI song) {
+        subject.addSong(song);
+    }
+
+    ...
+}
++---
+
+* 4. Use your class in the high-level client
+
+    Now, you can use your class with the high-level Solid client, mapping data seamlessly between your
+    Java application and an RDF resource.
+
++---
+public class MyApplication {
+
+    public void run() {
+        Session session = OpenIdConnect.ofClientCredentials(issuer, clientId, clientSecret, "client_secret_basic");
+        SolidSyncClient client = SolidSyncClient.getClient().session(session);
+
+        URI uri = URI.create("https://storage.example/playlists/910b509c-1ca5-4d6a-a093-377e8e1b390e");
+        try (Playlist playlist = client.read(uri, Playlist.class)) {
+            System.out.println(playlist.getTitle());
+
+            // Add a new song to the playlist
+            playlist.addSong(song);
+
+            // Update the playlist in your storage
+            client.update(playlist);
+        }
+    }
+}
++---
+
@@ -0,0 +1,41 @@
+Getting Started With Inrupt's Java Client Libraries
+
+    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.
+
+* What you will need
+
+    * About 15 minutes
+
+    * Your favorite text editor or IDE
+
+    * Java 11 or later
+
+    * Maven 3.5 or later
+
+* How to complete
+
+    First, issue the following command:
+
+-----------------
+$ mvn archetype:generate \
+    -DarchetypeGroupId=com.inrupt \
+    -DarchetypeArtifactId=inrupt-client-archetype-java
+-----------------
+
+    You will be prompted for a <<<groupId>>> value (e.g. <<<com.example>>>) and an <<<artifactId>>> value (e.g. <<<sample-project>>>).
+
+    Next, you will be able to find your new project in your current working directory.
+
+    To build this new project, issue the following commands:
+
+-----------------
+$ cd sample-project
+$ mvn install
+-----------------
+
+* Next steps
+
+    Your project will be configured to use a recommended collection of dependencies and provides a simple starting point for
+    building a Solid Application.
+
+    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}}.