Skip to content

Commit 713cd2a

Browse files
oexzaoexza
committed
docs: update installation and usage documentation
- Add comprehensive installation instructions for Maven and Gradle - Include multiple dependency management options (system path, local Maven, flat directory) - Expand quick start guide with complete OrisunClient and AdminClient examples - Add advanced configuration options documentation - Update release workflow to match new installation instructions
1 parent c075a82 commit 713cd2a

2 files changed

Lines changed: 260 additions & 35 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 88 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -184,70 +184,130 @@ jobs:
184184
185185
## Installation
186186
187-
### Option 1: Download JAR
187+
Download the `orisun-java-client-${{ needs.validate.outputs.version }}.jar` file from the assets below.
188188
189-
Download the JAR file from the assets below and add it to your project.
189+
### Maven
190190
191-
### Option 2: GitHub Packages
191+
**Option 1: System dependency**
192192
193-
Add to your `pom.xml`:
193+
Place the JAR in your project's `lib/` directory and add to `pom.xml`:
194194
195195
```xml
196-
<repository>
197-
<id>github</id>
198-
<url>https://maven.pkg.github.com/oexza/orisun-client-java</url>
199-
</repository>
196+
<dependency>
197+
<groupId>com.orisunlabs</groupId>
198+
<artifactId>orisun-java-client</artifactId>
199+
<version>${{ needs.validate.outputs.version }}</version>
200+
<scope>system</scope>
201+
<systemPath>${project.basedir}/lib/orisun-java-client-${{ needs.validate.outputs.version }}.jar</systemPath>
202+
</dependency>
203+
```
204+
205+
**Option 2: Install to local Maven repository**
206+
207+
```bash
208+
mvn install:install-file \
209+
-Dfile=orisun-java-client-${{ needs.validate.outputs.version }}.jar \
210+
-DgroupId=com.orisunlabs \
211+
-DartifactId=orisun-java-client \
212+
-Dversion=${{ needs.validate.outputs.version }} \
213+
-Dpackaging=jar
214+
```
215+
216+
Then add as a regular dependency in `pom.xml`:
200217
218+
```xml
201219
<dependency>
202220
<groupId>com.orisunlabs</groupId>
203221
<artifactId>orisun-java-client</artifactId>
204222
<version>${{ needs.validate.outputs.version }}</version>
205223
</dependency>
206224
```
207225
208-
Or for Gradle:
226+
### Gradle
227+
228+
**Option 1: Direct file dependency**
229+
230+
Place the JAR in your project's `libs/` directory and add to `build.gradle`:
209231
210232
```groovy
211-
repositories {
212-
maven { url 'https://maven.pkg.github.com/oexza/orisun-client-java' }
233+
dependencies {
234+
implementation files("libs/orisun-java-client-${{ needs.validate.outputs.version }}.jar")
213235
}
214-
215-
implementation 'com.orisunlabs:orisun-java-client:${{ needs.validate.outputs.version }}'
216236
```
217237
218-
**Note**: To use GitHub Packages, you'll need to authenticate:
238+
**Option 2: Flat directory repository**
219239
220240
```groovy
221-
// In ~/.gradle/gradle.properties
222-
githubUsername=YOUR_GITHUB_USERNAME
223-
githubPassword=YOUR_GITHUB_TOKEN
241+
repositories {
242+
flatDir { dirs 'libs' }
243+
}
244+
245+
dependencies {
246+
implementation "com.orisunlabs:orisun-java-client:${{ needs.validate.outputs.version }}"
247+
}
224248
```
225249
226-
Or in `pom.xml`:
250+
**Option 3: Build from source**
227251
228-
```xml
229-
<server>
230-
<id>github</id>
231-
<username>${env.GITHUB_USERNAME}</username>
232-
<password>${env.GITHUB_TOKEN}</password>
233-
</server>
252+
```bash
253+
git clone https://github.com/oexza/orisun-client-java.git
254+
cd orisun-client-java
255+
git submodule update --init --recursive
256+
./gradlew build
234257
```
235258
259+
The JAR will be at: `build/libs/orisun-client-${{ needs.validate.outputs.version }}.jar`
260+
236261
## Usage
237262
238263
See the [README](https://github.com/oexza/orisun-client-java) for detailed usage instructions.
239264
240-
Quick start:
265+
### Quick Start - OrisunClient (Event Operations)
241266
242267
```java
243268
import com.orisunlabs.orisun.client.OrisunClient;
269+
import com.orisun.eventstore.Eventstore;
244270
245-
OrisunClient client = OrisunClient.newBuilder()
271+
try (OrisunClient client = OrisunClient.newBuilder()
246272
.withServer("localhost", 5005)
247273
.withBasicAuth("admin", "changeit")
248-
.build();
274+
.build()) {
275+
276+
// Save events
277+
Eventstore.SaveEventsRequest request = Eventstore.SaveEventsRequest.newBuilder()
278+
.setBoundary("users")
279+
.addEvents(Eventstore.EventToSave.newBuilder()
280+
.setEventId(java.util.UUID.randomUUID().toString())
281+
.setEventType("UserCreated")
282+
.setData("{\"userId\":\"user-123\"}")
283+
.build())
284+
.build();
285+
286+
client.saveEvents(request);
287+
}
288+
```
289+
290+
### Quick Start - AdminClient (User Management)
249291
250-
// Use the client...
292+
```java
293+
import com.orisunlabs.orisun.client.AdminClient;
294+
import com.orisun.admin.AdminOuterClass.*;
295+
296+
try (AdminClient adminClient = AdminClient.newBuilder()
297+
.withServer("localhost", 5005)
298+
.withBasicAuth("admin", "changeit")
299+
.build()) {
300+
301+
// Create a user
302+
CreateUserRequest request = CreateUserRequest.newBuilder()
303+
.setName("John Doe")
304+
.setUsername("johndoe")
305+
.setPassword("securePassword123")
306+
.addRoles("user")
307+
.build();
308+
309+
AdminUser user = adminClient.createUser(request);
310+
}
251311
```
252312
files: release-artifacts/*
253313
draft: false

‎README.md‎

Lines changed: 172 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,52 @@ A Java client for the Orisun event store, providing a simple and intuitive inter
77
- **gRPC-based**: Built on gRPC for high-performance communication
88
- **Type-safe**: Generated from Protocol Buffer definitions
99
- **Easy to use**: Simple builder pattern for client configuration
10-
- **Authentication**: Support for basic authentication
10+
- **Authentication**: Support for basic authentication with token caching
11+
- **Dual Clients**: Includes both OrisunClient (event operations) and AdminClient (user management)
12+
- **Load Balancing**: Support for single-server, multi-server, DNS-based, and static load balancing
1113

1214
## Installation
1315

14-
### Maven
16+
### Download from GitHub Releases
17+
18+
The latest release JAR (with all dependencies included) can be downloaded from the [Releases](https://github.com/oexza/orisun-client-java/releases) page.
19+
20+
Download the `orisun-java-client-{version}.jar` file and follow the instructions below for your build system.
21+
22+
### Using in Your Project
23+
24+
#### Maven
25+
26+
1. Download the JAR file from the [Releases](https://github.com/oexza/orisun-client-java/releases) page
27+
2. Place the JAR in your project's `lib/` directory (or any directory you prefer)
28+
3. Add the following to your `pom.xml`:
29+
30+
```xml
31+
<dependencies>
32+
<dependency>
33+
<groupId>com.orisunlabs</groupId>
34+
<artifactId>orisun-java-client</artifactId>
35+
<version>0.0.1</version>
36+
<scope>system</scope>
37+
<systemPath>${project.basedir}/lib/orisun-java-client-0.0.1.jar</systemPath>
38+
</dependency>
39+
</dependencies>
40+
```
41+
42+
**Note**: Replace `0.0.1` with the actual version you downloaded and adjust the path if you placed the JAR in a different location.
43+
44+
Alternatively, you can install the JAR to your local Maven repository:
45+
46+
```bash
47+
mvn install:install-file \
48+
-Dfile=orisun-java-client-0.0.1.jar \
49+
-DgroupId=com.orisunlabs \
50+
-DartifactId=orisun-java-client \
51+
-Dversion=0.0.1 \
52+
-Dpackaging=jar
53+
```
54+
55+
Then add it as a regular dependency:
1556

1657
```xml
1758
<dependency>
@@ -21,13 +62,59 @@ A Java client for the Orisun event store, providing a simple and intuitive inter
2162
</dependency>
2263
```
2364

24-
### Gradle
65+
#### Gradle
66+
67+
**Option 1: Direct file dependency**
68+
69+
1. Download the JAR file from the [Releases](https://github.com/oexza/orisun-client-java/releases) page
70+
2. Place the JAR in your project's `libs/` directory
71+
3. Add the following to your `build.gradle`:
72+
73+
```groovy
74+
dependencies {
75+
implementation files('libs/orisun-java-client-0.0.1.jar')
76+
}
77+
```
78+
79+
**Option 2: Flat directory repository**
80+
81+
1. Create a `libs/` directory in your project
82+
2. Place the JAR file in the `libs/` directory
83+
3. Add the following to your `build.gradle`:
84+
85+
```groovy
86+
repositories {
87+
flatDir {
88+
dirs 'libs'
89+
}
90+
}
91+
92+
dependencies {
93+
implementation 'com.orisunlabs:orisun-java-client:0.0.1'
94+
}
95+
```
96+
97+
**Option 3: Local Maven repository**
98+
99+
First, install the JAR to your local Maven repository:
100+
101+
```bash
102+
./gradlew publishToMavenLocal
103+
```
104+
105+
Then add it to your project's `build.gradle`:
25106

26107
```groovy
27-
implementation 'com.orisunlabs:orisun-java-client:0.0.1'
108+
repositories {
109+
mavenLocal()
110+
}
111+
112+
dependencies {
113+
implementation 'com.orisunlabs:orisun-java-client:0.0.1'
114+
}
28115
```
29116

30-
## Building from Source
117+
### Building from Source
31118

32119
```bash
33120
# Clone the repository
@@ -39,6 +126,8 @@ git submodule update --init --recursive
39126

40127
# Build with Gradle
41128
./gradlew build
129+
130+
# The fat JAR with dependencies will be at: build/libs/orisun-client-{version}.jar
42131
```
43132

44133
## Proto Files
@@ -55,16 +144,92 @@ git submodule update --remote protos
55144

56145
## Quick Start
57146

147+
### OrisunClient - Event Store Operations
148+
58149
```java
59150
import com.orisunlabs.orisun.client.OrisunClient;
151+
import com.orisun.eventstore.Eventstore;
152+
import java.util.UUID;
60153

61154
// Create a client
155+
try (OrisunClient client = OrisunClient.newBuilder()
156+
.withServer("localhost", 5005)
157+
.withBasicAuth("admin", "changeit")
158+
.build()) {
159+
160+
// Save events
161+
Eventstore.SaveEventsRequest request = Eventstore.SaveEventsRequest.newBuilder()
162+
.setBoundary("users")
163+
.addEvents(Eventstore.EventToSave.newBuilder()
164+
.setEventId(UUID.randomUUID().toString())
165+
.setEventType("UserCreated")
166+
.setData("{\"userId\":\"user-123\",\"email\":\"john@example.com\"}")
167+
.build())
168+
.build();
169+
170+
Eventstore.WriteResult result = client.saveEvents(request);
171+
172+
// Read events
173+
Eventstore.GetEventsResponse response = client.getEvents(
174+
Eventstore.GetEventsRequest.newBuilder()
175+
.setBoundary("users")
176+
.setCount(10)
177+
.build()
178+
);
179+
}
180+
```
181+
182+
### AdminClient - User Management
183+
184+
```java
185+
import com.orisunlabs.orisun.client.AdminClient;
186+
import com.orisun.admin.AdminOuterClass.*;
187+
188+
// Create an admin client
189+
try (AdminClient adminClient = AdminClient.newBuilder()
190+
.withServer("localhost", 5005)
191+
.withBasicAuth("admin", "changeit")
192+
.build()) {
193+
194+
// Create a user
195+
CreateUserRequest createRequest = CreateUserRequest.newBuilder()
196+
.setName("John Doe")
197+
.setUsername("johndoe")
198+
.setPassword("securePassword123")
199+
.addRoles("user")
200+
.build();
201+
202+
AdminUser user = adminClient.createUser(createRequest);
203+
204+
// List all users
205+
List<AdminUser> users = adminClient.listUsers();
206+
207+
// Validate credentials
208+
ValidateCredentialsResponse response = adminClient.validateCredentials(
209+
ValidateCredentialsRequest.newBuilder()
210+
.setUsername("johndoe")
211+
.setPassword("securePassword123")
212+
.build()
213+
);
214+
}
215+
```
216+
217+
### Advanced Configuration
218+
219+
Both clients support advanced configuration:
220+
221+
```java
62222
OrisunClient client = OrisunClient.newBuilder()
63223
.withServer("localhost", 5005)
64224
.withBasicAuth("admin", "changeit")
225+
.withTimeout(30) // Request timeout in seconds
226+
.withTls(false) // Use TLS
227+
.withLoadBalancingPolicy("round_robin") // Load balancing policy
228+
.withKeepAliveTime(30000) // Keep-alive time in ms
229+
.withKeepAliveTimeout(10000) // Keep-alive timeout in ms
230+
.withLogging(true) // Enable logging
231+
.withLogLevel(com.orisunlabs.orisun.client.DefaultLogger.LogLevel.INFO)
65232
.build();
66-
67-
// Use the client...
68233
```
69234

70235
## License

0 commit comments

Comments
 (0)