diff --git a/README.md b/README.md index 32e8d699..9e0a8034 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Take a look at [CONTRIBUTING](CONTRIBUTING.md) for specifics on how to contribut [JavaDocs](https://janeirodigital.github.io/sai-java/) are generated and published with each release. -## Getting Started +## Installation In your `pom.xml`: @@ -28,3 +28,49 @@ In your `pom.xml`: ``` + +## Getting Started + +This library implements all of the patterns defined in the +[Solid Application Interoperability Specification](https://solid.github.io/data-interoperability-panel/specification/), +which will hereafter be referred to as "the specification". +Consequently, becoming familiar with that text and the patterns therein will be helpful, and we will link to the +pertinent ones throughout. + +### Initializing the Application + +The first thing your application will need to do is initialize an `Application` instance. An application instance +in this context represents an [Application](https://solid.github.io/data-interoperability-panel/specification/) +as defined in the specification. + +```java +URI applicationId = URI.create("https://projectron.example/id"); +AuthorizedSessionAccessor sessionAccessor = new BasicAuthorizedSessionAccessor(); +boolean validateSsl = true; +boolean validateShapeTrees = false; +boolean refreshTokens = true; +Application app = new Application(applicationId, validateSsl, validateShapeTrees, refreshTokens, sessionAccessor); +``` + +Lets break down the parameters provided above: + +* `applicationId`: This is the URI of the Application's Profile ID. Effectively, the WebID of the Application. + +* `sessionAccessor`: This is an implementation of the +[`AuthorizedSessionAccessor`](https://janeirodigital.github.io/sai-authentication-java/com/janeirodigital/sai/authentication/AuthorizedSessionAccessor.html) +interface as defined by +[sai-authentication-java](https://github.com/janeirodigital/sai-authentication-java). +It lets the application get and put authorized session credentials used to interface +with a given Social Agent's data on their behalf. A basic in-memory implementation is +provided along with that library, but production +scenarios may want to provide a more robust implementation with something like Redis +or even an RDBMS. + +* `validateSsl`: Toggle whether to skip SSL validation and errors. **Only for use in development or test scenarios**. + +* `validateShapeTrees`: Toggle whether to enable client-side shape tree validation. Useful when storage servers +do not apply server-side validation. When false, no validation will be applied. This validation is performed +by intercepting requests sent and received via OkHttpClient instances. + +* `refreshTokens`: Toggle whether to refresh tokens automatically when they expire. +