Skip to content

Commit ba9df7e

Browse files
Copilotbastianeicher
Copilot
and
bastianeicher
committed
Add Java and Kotlin examples to link-handling documentation
Co-authored-by: bastianeicher <414366+bastianeicher@users.noreply.github.com>
1 parent e83064f commit ba9df7e

5 files changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/link-handling/hal.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,30 @@ After receiving a HAL response, you can resolve links just like with HTTP Link h
4040
Uri userUri = endpoint.LinkTemplate("search", new { id = "456" });
4141
```
4242

43+
=== "Java"
44+
45+
```java
46+
endpoint.read();
47+
48+
// Resolve a single link
49+
URI ordersUri = endpoint.link("orders");
50+
51+
// Resolve a templated link
52+
URI userUri = endpoint.linkTemplate("search", Map.of("id", "456"));
53+
```
54+
55+
=== "Kotlin"
56+
57+
```kotlin
58+
endpoint.read()
59+
60+
// Resolve a single link
61+
val ordersUri = endpoint.link("orders")
62+
63+
// Resolve a templated link
64+
val userUri = endpoint.linkTemplate("search", mapOf("id" to "456"))
65+
```
66+
4367
=== "TypeScript"
4468

4569
```typescript
@@ -79,6 +103,24 @@ Retrieve all links with `GetLinks`:
79103
}
80104
```
81105

106+
=== "Java"
107+
108+
```java
109+
List<Link> items = endpoint.getLinks("item");
110+
for (Link link : items) {
111+
System.out.println(link.getTitle() + ": " + link.getUri());
112+
}
113+
```
114+
115+
=== "Kotlin"
116+
117+
```kotlin
118+
val items = endpoint.getLinks("item")
119+
for (link in items) {
120+
println("${link.title}: ${link.uri}")
121+
}
122+
```
123+
82124
=== "TypeScript"
83125

84126
```typescript
@@ -110,6 +152,20 @@ HAL links can be marked as [templates](uri-templates.md) with the `templated` pr
110152
// Result: /users?name=John&email=john%40example.com
111153
```
112154

155+
=== "Java"
156+
157+
```java
158+
URI findUri = endpoint.linkTemplate("find", Map.of("name", "John", "email", "john@example.com"));
159+
// Result: /users?name=John&email=john%40example.com
160+
```
161+
162+
=== "Kotlin"
163+
164+
```kotlin
165+
val findUri = endpoint.linkTemplate("find", mapOf("name" to "John", "email" to "john@example.com"))
166+
// Result: /users?name=John&email=john%40example.com
167+
```
168+
113169
=== "TypeScript"
114170

115171
```typescript

‎docs/link-handling/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,18 @@ All endpoints provide methods for resolving links:
1717
- `Link(rel)` - Resolves a single link with a specific relation type
1818
- `LinkTemplate(rel, variables)` - Resolves a link template with variables
1919

20+
=== "Java"
21+
22+
- `getLinks(rel)` - Resolves all links with a specific relation type
23+
- `link(rel)` - Resolves a single link with a specific relation type
24+
- `linkTemplate(rel, variables)` - Resolves a link template with variables
25+
26+
=== "Kotlin"
27+
28+
- `getLinks(rel)` - Resolves all links with a specific relation type
29+
- `link(rel)` - Resolves a single link with a specific relation type
30+
- `linkTemplate(rel, variables)` - Resolves a link template with variables
31+
2032
=== "TypeScript"
2133

2234
- `getLinks(rel)` - Resolves all links with a specific relation type

‎docs/link-handling/link-header.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,38 @@ TypedRest automatically extracts links from response headers after each request.
3737
Uri collectionUri = endpoint.Link("next");
3838
```
3939

40+
=== "Java"
41+
42+
```java
43+
// Perform a request
44+
endpoint.read();
45+
46+
// Get all links with a specific relation type
47+
List<Link> links = endpoint.getLinks("child");
48+
for (Link link : links) {
49+
System.out.println("URI: " + link.getUri() + ", Title: " + link.getTitle());
50+
}
51+
52+
// Get a single link
53+
URI collectionUri = endpoint.link("next");
54+
```
55+
56+
=== "Kotlin"
57+
58+
```kotlin
59+
// Perform a request
60+
endpoint.read()
61+
62+
// Get all links with a specific relation type
63+
val links = endpoint.getLinks("child")
64+
for (link in links) {
65+
println("URI: ${link.uri}, Title: ${link.title}")
66+
}
67+
68+
// Get a single link
69+
val collectionUri = endpoint.link("next")
70+
```
71+
4072
=== "TypeScript"
4173

4274
```typescript
@@ -73,6 +105,26 @@ This is a non-standard extension, but it allows servers to provide dynamic link
73105
// Result: http://example.com/users/123
74106
```
75107

108+
=== "Java"
109+
110+
```java
111+
// Server response:
112+
// Link: </users/{id}>; rel=user; templated=true
113+
114+
URI userUri = endpoint.linkTemplate("user", Map.of("id", "123"));
115+
// Result: http://example.com/users/123
116+
```
117+
118+
=== "Kotlin"
119+
120+
```kotlin
121+
// Server response:
122+
// Link: </users/{id}>; rel=user; templated=true
123+
124+
val userUri = endpoint.linkTemplate("user", mapOf("id" to "123"))
125+
// Result: http://example.com/users/123
126+
```
127+
76128
=== "TypeScript"
77129

78130
```typescript

‎docs/link-handling/relative-uris.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,22 @@ The most straightforward way to navigate between endpoints is using hard-coded r
1212
// Results in: http://example.com/api/contacts
1313
```
1414

15+
=== "Java"
16+
17+
```java
18+
EntryEndpoint client = new EntryEndpoint(URI.create("http://example.com/api/"));
19+
CollectionEndpoint<Contact> contacts = new CollectionEndpoint<>(client, "contacts", Contact.class);
20+
// Results in: http://example.com/api/contacts
21+
```
22+
23+
=== "Kotlin"
24+
25+
```kotlin
26+
val client = EntryEndpoint(URI.create("http://example.com/api/"))
27+
val contacts = CollectionEndpoint(client, "contacts", Contact::class.java)
28+
// Results in: http://example.com/api/contacts
29+
```
30+
1531
=== "TypeScript"
1632

1733
```typescript
@@ -45,6 +61,36 @@ This is often not the desired behavior. TypedRest provides a non-standard `./` p
4561
// child2.Uri = http://example.com/endpoint/subresource
4662
```
4763

64+
=== "Java"
65+
66+
```java
67+
ElementEndpoint<MyEntity> parent = new ElementEndpoint<>(client, "endpoint", MyEntity.class);
68+
// parent.getUri() = http://example.com/endpoint
69+
70+
// Without ./ prefix - replaces last segment
71+
ActionEndpoint child1 = new ActionEndpoint(parent, "subresource");
72+
// child1.getUri() = http://example.com/subresource
73+
74+
// With ./ prefix - appends to path
75+
ActionEndpoint child2 = new ActionEndpoint(parent, "./subresource");
76+
// child2.getUri() = http://example.com/endpoint/subresource
77+
```
78+
79+
=== "Kotlin"
80+
81+
```kotlin
82+
val parent = ElementEndpoint(client, "endpoint", MyEntity::class.java)
83+
// parent.uri = http://example.com/endpoint
84+
85+
// Without ./ prefix - replaces last segment
86+
val child1 = ActionEndpoint(parent, "subresource")
87+
// child1.uri = http://example.com/subresource
88+
89+
// With ./ prefix - appends to path
90+
val child2 = ActionEndpoint(parent, "./subresource")
91+
// child2.uri = http://example.com/endpoint/subresource
92+
```
93+
4894
=== "TypeScript"
4995

5096
```typescript
@@ -79,6 +125,27 @@ You can also register default links that will be used when the server doesn't pr
79125
}
80126
```
81127

128+
=== "Java"
129+
130+
```java
131+
class MyEndpoint extends AbstractEndpoint {
132+
public MyEndpoint(Endpoint referrer, String relativeUri) {
133+
super(referrer, relativeUri);
134+
setDefaultLink("related", "./related-resource");
135+
}
136+
}
137+
```
138+
139+
=== "Kotlin"
140+
141+
```kotlin
142+
class MyEndpoint(referrer: Endpoint, relativeUri: String) : AbstractEndpoint(referrer, relativeUri) {
143+
init {
144+
setDefaultLink("related", "./related-resource")
145+
}
146+
}
147+
```
148+
82149
=== "TypeScript"
83150

84151
```typescript

‎docs/link-handling/uri-templates.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,30 @@ Use the `LinkTemplate` method to resolve a template with variables:
5050
var uri = endpoint.LinkTemplate("user", variables);
5151
```
5252

53+
=== "Java"
54+
55+
```java
56+
// After receiving a response with the link template
57+
URI userUri = endpoint.linkTemplate("user", Map.of("id", "123"));
58+
// Result: http://example.com/users/123
59+
60+
// With query parameters
61+
URI searchUri = endpoint.linkTemplate("search", Map.of("q", "test", "limit", 10));
62+
// Result: http://example.com/search?q=test&limit=10
63+
```
64+
65+
=== "Kotlin"
66+
67+
```kotlin
68+
// After receiving a response with the link template
69+
val userUri = endpoint.linkTemplate("user", mapOf("id" to "123"))
70+
// Result: http://example.com/users/123
71+
72+
// With query parameters
73+
val searchUri = endpoint.linkTemplate("search", mapOf("q" to "test", "limit" to 10))
74+
// Result: http://example.com/search?q=test&limit=10
75+
```
76+
5377
=== "TypeScript"
5478

5579
```typescript
@@ -80,6 +104,29 @@ You can register default link templates that will be used when the server doesn'
80104
}
81105
```
82106

107+
=== "Java"
108+
109+
```java
110+
class MyEndpoint extends AbstractEndpoint {
111+
public MyEndpoint(Endpoint referrer, String relativeUri) {
112+
super(referrer, relativeUri);
113+
// Set a default template for the "child" relation
114+
setDefaultLinkTemplate("child", "./{id}");
115+
}
116+
}
117+
```
118+
119+
=== "Kotlin"
120+
121+
```kotlin
122+
class MyEndpoint(referrer: Endpoint, relativeUri: String) : AbstractEndpoint(referrer, relativeUri) {
123+
init {
124+
// Set a default template for the "child" relation
125+
setDefaultLinkTemplate("child", "./{id}")
126+
}
127+
}
128+
```
129+
83130
=== "TypeScript"
84131

85132
```typescript

0 commit comments

Comments
 (0)