Skip to content

Commit abf375b

Browse files
author
guylabs
committed
Update LICENSE and README files. Change copyright.
1 parent 66b9c0b commit abf375b

File tree

4 files changed

+215
-218
lines changed

4 files changed

+215
-218
lines changed

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2013 Jeremy Marquis
3+
Copyright (c) 2013 Guy Brûlé
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 214 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,215 @@
1-
angular-spring-data-rest
2-
========================
1+
# angular-spring-data-rest
32

4-
An AngularJS module for using $resource with a Spring Data REST backend.
3+
> An AngularJS module with an additional interceptor which wraps the Angular [$resource](https://docs.angularjs.org/api/ngResource/service/$resource) function and therefore eases the use with a [Spring Data REST](http://projects.spring.io/spring-data-rest) backend.
4+
5+
==========================
6+
7+
## Overview
8+
9+
*Spring Data REST* integrates [Spring HATEOAS](http://projects.spring.io/spring-hateoas) by default. This simplifies the creation of REST presentations which are generated with the [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS) principle.
10+
11+
Therefore the *Spring Data REST* responses have links and embedded resources like in the following JSON response example:
12+
13+
```json
14+
{
15+
"_links": {
16+
"self": {
17+
"href": "http://localhost:8080/categories{?page,size,sort}",
18+
"templated": true
19+
}
20+
},
21+
"_embedded": {
22+
"categories": [
23+
{
24+
"name": "Test category 1",
25+
"_links": {
26+
"self": {
27+
"href": "http://localhost:8080/categories/1"
28+
},
29+
"parentCategory": {
30+
"href": "http://localhost:8080/categories/1/parentCategory"
31+
}
32+
}
33+
},
34+
{
35+
"name": "Test category 2",
36+
"_links": {
37+
"self": {
38+
"href": "http://localhost:8080/categories/2"
39+
},
40+
"parentCategory": {
41+
"href": "http://localhost:8080/categories/2/parentCategory"
42+
}
43+
}
44+
}
45+
]
46+
},
47+
"page": {
48+
"size": 20,
49+
"totalElements": 2,
50+
"totalPages": 1,
51+
"number": 0
52+
}
53+
}
54+
```
55+
The above response is the result of calling the endpoint to get all categories(`http://localhost:8080/categories`). It contains the `_links` property which holds an object with several named links(e.g. `self`). These links are used to navigate to a related entity(e.g. `parentCategory`) or to a specific endpoint defined by the backend.
56+
57+
The `_embedded` property holds an array of the requested items, and each of the items has again a `_links` property which defines the links for the specific item. You can find more about how the responses of *Spring Data REST* [here](http://projects.spring.io/spring-data-rest).
58+
59+
This *Angular* module provides two ways of processing a response from the *Spring Data REST* backend and ease the usage with the links and embedded resources:
60+
61+
1. Using a new instance of the `SpringDataRestAdapter`.
62+
2. Add the `SpringDataRestInterceptor` to the Angular `$httpProvider.interceptors` such that all responses are processed.
63+
64+
## The `SpringDataRestAdapter`
65+
66+
The `spring-data-rest` *Angular* module provides a provider for the `SpringDataRestAdapter` object. This object is the core of the module and it processes a given response and adds the following additional properties/methods to it:
67+
68+
1. `_resource`: this method wraps the *Angular* `$resource` function and adds an easy way to call the links defined in the `_links` property. Read more about this property [here](#usage-of-_resource-property).
69+
2. `_embeddedItems`: this property replaces the `_embedded` property and sets the named array (`categories` in the upper example response) with the embedded items as its value. Read more about this property [here](#usage-of-_embeddedItems-property).
70+
71+
### Usage of `SpringDataRestAdapter`
72+
73+
To use the `SpringDataRestAdapter` object you need to include the `angular-spring-data-rest.js` file (or the minified version) and add the `spring-data-rest` module as a dependency in your module declaration:
74+
75+
```javascript
76+
var myApp = angular.module("myApplication", ["ngResource", "spring-data-rest"]);
77+
```
78+
79+
Now you are able to instantiate the `SpringDataRestAdapter` object and process a given response:
80+
81+
```javascript
82+
var processedResponse = new SpringDataRestAdapter(response);
83+
```
84+
85+
Please read on on how to use the `_resource` method and the `_embeddedItems` property to ease the handling of links and embedded items.
86+
87+
### Usage of `_resource` method
88+
89+
The `_resource` property is added on the same level of the JSON response object where a `_links` property exists. When for example the following JSON response object is given:
90+
91+
```javascript
92+
var response = {
93+
"_links": {
94+
"self": {
95+
"href": "http://localhost:8080/categories{?page,size,sort}",
96+
"templated": true
97+
}
98+
},
99+
"_embedded": {
100+
...
101+
}
102+
...
103+
}
104+
var processedResponse = new SpringDataRestAdapter(response);
105+
```
106+
107+
Then the `SpringDataRestAdapter` will add the `_resource` method to the same level such that you can call it the following way:
108+
109+
```javascript
110+
processedResponse._resource(linkName, paramDefaults, actions, options);
111+
```
112+
113+
This `_resource` method is added recursively to all the properties of the JSON response object where a `_links` property exists.
114+
115+
#### The `_resource` method parameters and return type
116+
117+
The `_resource` method takes the following four parameters:
118+
119+
1. `linkName`: the name of the link's `href` you want to call with the underlying *Angular* `$resource` function.
120+
2. `paramDefaults`: the default values for url parameters. Read more [here](https://docs.angularjs.org/api/ngResource/service/$resource).
121+
3. `actions`: custom action that should extend the default set of the `$resource` actions. Read more [here](https://docs.angularjs.org/api/ngResource/service/$resource).
122+
4. `options`: custom settings that should extend the default `$resourceProvider` behavior Read more [here](https://docs.angularjs.org/api/ngResource/service/$resource).
123+
124+
The `_resource` method returns the *Angular* resource "class" object with methods for the default set of resource actions. Read more [here](https://docs.angularjs.org/api/ngResource/service/$resource).
125+
126+
##### Example
127+
128+
This example refers to the JSON response in the [Overview](#overview). If you want to get the parent category of a category you would call the `_resource` method the following way:
129+
130+
```javascript
131+
var processedResponse = new SpringDataRestAdapter(response);
132+
var parentCategoryResource = processedResponse._embeddedItems[0]._resource("parentCategory");
133+
134+
// create a GET request, with the help of the Angular resource class, to the parent category
135+
// url and log the response to the console
136+
var parentCategory = parentCategoryResource.get(function() {
137+
console.log("Parent category name: " + parentCategory.name);
138+
});
139+
```
140+
141+
### Usage of `_embeddedItems` property
142+
143+
The `_embeddedItems` property is just a convention property created by the `SpringDataRestAdapter` to easily iterate over the `_emebedded` items in the response. Like with the `_resource` method, the `SpringDataRestAdapter` will recursively create an `_embeddedItems` property on the same level as a `_embedded` property exists for all the JSON response properties.
144+
145+
#### Example
146+
147+
This example refers to the JSON response in the [Overview](#overview). If you want to iterate over all categories in the response you would do it in the following way:
148+
149+
```javascript
150+
var processedResponse = new SpringDataRestAdapter(response);
151+
152+
// log the name of all categories contained in the response to the console
153+
angular.forEach(processedResponse._embeddedItems, function (category, key) {
154+
console.log("Category name: " + category.name);
155+
});
156+
```
157+
158+
**Be aware** that the original `_embedded` property gets deleted after the `SpringDataRestAdapter` processed the response.
159+
160+
161+
### Configuration of the `SpringDataRestAdapter`
162+
163+
The `SpringDataRestAdapter` is designed to be configurable and you are able to configure the following properties:
164+
165+
* `links.key` (default: `_links`): the property name where the links are stored.
166+
* `embedded.key` (default: `_embedded`): the property name where the embedded items are stored.
167+
* `embedded.value` (default: `_embeddedItems`): the property name where the array of embedded items are stored.
168+
* `hrefKey` (default: `href`): the property name where the url is stored under each specific link.
169+
* `resourceKey` (default: `_resource`): the property name where the resource method is stored.
170+
171+
You are able to configure the `SpringDataRestAdapter` provider in a *Angular* configuration block in the following way:
172+
173+
```javascript
174+
myApp.config(function (SpringDataRestAdapterProvider) {
175+
176+
// set the links key to _myLinks
177+
SpringDataRestAdapterProvider.config({
178+
'links': {
179+
'key': '_myLinks'
180+
}
181+
});
182+
});
183+
```
184+
185+
The config method of the `SpringDataRestAdapterProvider` takes a configuration object and you are able to override each value or completely replace the whole configuration object. The default configuration object looks like this:
186+
187+
```json
188+
{
189+
"links": {
190+
"key": "_links"
191+
},
192+
"embedded": {
193+
"key": "_embedded",
194+
"value': "_embeddedItems"
195+
},
196+
"hrefKey": "href",
197+
"resourceKey": "_resource"
198+
}
199+
```
200+
201+
202+
## The `SpringDataRestInterceptor`
203+
204+
If you want to use the `SpringDataRestAdapter` for all responses of the *Angular* `$http` service then you can add the `SpringDataRestInterceptor` to the `$httpProvider.interceptors` in an *Angular* configuration block:
205+
206+
```javascript
207+
myApp.config(function (SpringDataRestInterceptorProvider) {
208+
SpringDataRestInterceptorProvider.apply();
209+
});
210+
```
211+
The `apply` method will automatically add the `SpringDataRestInterceptor` to the `$httpProvider.interceptors`.
212+
213+
## Dependencies
214+
215+
The `spring-data-rest` *Angular* module requires the `ngResource` *Angular* module.

‎bower.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
"name": "angular-spring-data-rest",
33
"version": "0.1.0",
44
"authors": [
5-
"Jeremy Marquis <jeremy@jeremymarquis.com>",
65
"Guy Brûlé <admin@guylabs.org>"
76
],
87
"description": "An AngularJS module for using `$resource` with a Spring Data REST backend.",

0 commit comments

Comments
 (0)