Spring4 MVC RESTFul WebServices CRUD實例+RestTemplate
在這篇文章中,我們將使用Spring4 MVC編寫一個CRUD RESTful Web服務,寫一個REST客戶端RestTemplate來使用這些服務。我們也將利用外部客戶端測試的服務。
簡單介紹REST
REST 表示狀態傳輸。這是一個體繫結構樣式,可用於設計網絡服務,可以被各種客戶端消耗。核心思想是,不使用如CORBA,RPC或SOAP複雜的機制在機器之間進行連接,簡單的 HTTP 用於使它們之間調用。
在基於 REST 的設計中,資源被一套通用動詞操作使用。
創建資源:應該使用 HTTP POST
要獲取資源:應該使用HTTP GET
更新資源:應使用HTTP PUT
要刪除資源:應使用HTTP DELETE
這意味着,作爲一個 REST 服務開發人員或客戶端,應符合上述標準,以便 REST 操作。
通常Rest 是基於Web服務返回JSON或XML數據格式作爲響應,雖然它並不僅僅限於這些類型。客戶端可以指定(使用 HTTP Accept 報頭),他們所感興趣的資源類型,並且服務器可以返回資源,指定它所服務的內容類型資源。
基於REST的控制器
下面是一個可能基於 REST 的控制器,實現REST API。這裏所說的「可能」,這意味着可以以另一種方式實現它,還是(或者更純粹的方式)符合REST風格。
這就是我們的 REST API 功能/作用:
- GET 請求 /api/user/ 返回用戶的列表
- GET 請求 /api/user/1 返回ID爲1的用戶
- POST 請求 /api/user/ 以用戶對象的JSON格式創建新的用戶
- PUT 請求 /api/user/3 以用戶對象作爲JSON更新ID爲3的用戶
- DELETE 請求 /api/user/4 刪除ID爲4的用戶
- DELETE 請求 /api/user/ 刪除所有的用戶
package com.yiibai.springmvc.controller;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.util.UriComponentsBuilder;
import com.yiibai.springmvc.model.User;
import com.yiibai.springmvc.service.UserService;
@RestController
public class HelloWorldRestController {
@Autowired
UserService userService; //Service which will do all data retrieval/manipulation work
//-------------------Retrieve All Users--------------------------------------------------------
@RequestMapping(value = "/user/", method = RequestMethod.GET)
public ResponseEntity<List<User>> listAllUsers() {
List<User> users = userService.findAllUsers();
if(users.isEmpty()){
return new ResponseEntity<List<User>>(HttpStatus.NO_CONTENT);//You many decide to return HttpStatus.NOT_FOUND
}
return new ResponseEntity<List<User>>(users, HttpStatus.OK);
}
//-------------------Retrieve Single User--------------------------------------------------------
@RequestMapping(value = "/user/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<User> getUser(@PathVariable("id") long id) {
System.out.println("Fetching User with id " + id);
User user = userService.findById(id);
if (user == null) {
System.out.println("User with id " + id + " not found");
return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
}
return new ResponseEntity<User>(user, HttpStatus.OK);
}
//-------------------Create a User--------------------------------------------------------
@RequestMapping(value = "/user/", method = RequestMethod.POST)
public ResponseEntity<Void> createUser(@RequestBody User user, UriComponentsBuilder ucBuilder) {
System.out.println("Creating User " + user.getName());
if (userService.isUserExist(user)) {
System.out.println("A User with name " + user.getName() + " already exist");
return new ResponseEntity<Void>(HttpStatus.CONFLICT);
}
userService.saveUser(user);
HttpHeaders headers = new HttpHeaders();
headers.setLocation(ucBuilder.path("/user/{id}").buildAndExpand(user.getId()).toUri());
return new ResponseEntity<Void>(headers, HttpStatus.CREATED);
}
//------------------- Update a User --------------------------------------------------------
@RequestMapping(value = "/user/{id}", method = RequestMethod.PUT)
public ResponseEntity<User> updateUser(@PathVariable("id") long id, @RequestBody User user) {
System.out.println("Updating User " + id);
User currentUser = userService.findById(id);
if (currentUser==null) {
System.out.println("User with id " + id + " not found");
return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
}
currentUser.setName(user.getName());
currentUser.setAge(user.getAge());
currentUser.setSalary(user.getSalary());
userService.updateUser(currentUser);
return new ResponseEntity<User>(currentUser, HttpStatus.OK);
}
//------------------- Delete a User --------------------------------------------------------
@RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE)
public ResponseEntity<User> deleteUser(@PathVariable("id") long id) {
System.out.println("Fetching & Deleting User with id " + id);
User user = userService.findById(id);
if (user == null) {
System.out.println("Unable to delete. User with id " + id + " not found");
return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
}
userService.deleteUserById(id);
return new ResponseEntity<User>(HttpStatus.NO_CONTENT);
}
//------------------- Delete All Users --------------------------------------------------------
@RequestMapping(value = "/user/", method = RequestMethod.DELETE)
public ResponseEntity<User> deleteAllUsers() {
System.out.println("Deleting All Users");
userService.deleteAllUsers();
return new ResponseEntity<User>(HttpStatus.NO_CONTENT);
}
}
詳細說明:
@RestController
: 首先,我們使用 Spring4 的新 @RestController 註釋。 它的註解消除了註釋每個以@ResponseBody的方法。@RestController本身註解爲@ResponseBody,並且可以被視爲@Controller和@ResponseBody的組合。
@RequestBody
: 如果一個方法的參數都註解有@RequestBody,Spring將綁定傳入的 HTTP 請求體(在@RequestMapping提到該法的URL)到這個參數。這樣做 Spring 將[在後臺]使用HTTP消息轉換爲HTTP請求主體轉換成域對象[反序列化要求主體域對象]的基礎上,接受或Content-Type頭請求。
@ResponseBody
:如果一個方法被註解爲@ResponseBody,Spring將綁定返回值傳出的 HTTP 響應體。這樣做Spring將[在後臺]使用HTTP消息轉換器的返回值轉換爲HTTP響應體[序列化對象響應正文],根據內容類型出現在請求的HTTP頭。 前面已經提到,在 Spring4 可能會停止使用此註釋。
ResponseEntity
是一個真正處理。 它代表了整個HTTP響應。一件好事是你可以控制任何進入它東西。可以指定狀態碼,頭和主體。它自帶幾個構造函數執行你想要的 HTTP 響應發送的信息。
@PathVariable
這種表示法表示方法參數應綁定到一個 URI 模板變量[「{}」]。
基本上,@RestController,@RequestBody,ResponseEntity&@PathVariable 都是用 Spring 4 實現 REST API 需要知道的。此外,Spring提供了一些支持類來幫助你實現一些定製。
MediaType : 通過@RequestMapping註解,你還可以,指定要生產或消費的 MediaType(使用生產或消費屬性),通過特定的控制器的方法,以進一步縮小映射。
部署並測試API,讓我們深入研究這個東西是如何工作的
它只是一個普通的控制器類,可部署的應用程序的一部分。[完整下載的應用程序代碼顯示在本教程文章最後,你可以直接部署到容器。先部署它,纔能有這些可用服務,這裏先詳細討論了每一個操作。部署的應用程序並訪問:http://localhost:8080/Spring4MVCCRUDRestService.
爲了測試這個API,這裏使用一個外部客戶端POSTMAN(這是一個 Chrome 插件,下載安裝:http://www.getpostman.com/)。後面我們也將編寫我們自己的客戶端,也就幾分鐘的時間。
1. 檢索所有用戶
打開POSTMAN 工具中,選擇請求類型[GET這個用例],指定操作URI。訪問: http://localhost:8080/Spring4MVCCRUDRestService/user/
請注意,我們這裏沒有指定任何HTTP標頭。點擊發送(Send),您將收到的所有用戶的列表。
還要注意 HTTP 200 響應。此外這裏查看一下報頭。
你可能想知道的響應是如何發送 JSON 字符串,並在響應中確認Content-Type頭。這已在我們的項目Jackson庫中實現。
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.5.3</version>
</dependency>
由於 Spring 找到這個庫在 classpath 中,它調用內置MappingJackson2HttpMessageConverter 轉換器轉換成JSON響應(對象的列表)。
關於Spring內置轉換器,大部分的時間他們只需要某些庫在類路徑中以便進行轉換。當然,有時我們也需要去適應我們的 API/應用程序也是如此。舉例來說,如果我們想爲XML,我們應標註適當JAXB標註User類。
2. 檢索單用戶
指定 GET /user/1,點擊發送(Send)。
如果發送的是無效標識符的GET,您會收到一個HTTP 404。
3. 創建一個用戶
選擇方法POST,指定的URI爲/user/,在 POSTMAN 主體標籤中指定主體,選擇類型[application/json]。
您可能已經注意到,POSTMAN會自動添加一個頭 Content-Type 。
隨着POST和PUT請求,客戶端將數據發送到服務器,它們應指定正在發送的數據的實際內容類型。
發送。您應該看到HTTP200響應,沒有主體(如API不發送主體任何東西)。但是,你應該找一個Location頭指定位置新創建的用戶。
現在,您可以獲取新創建的用戶。
通過這種方式實現是常見的REST。但是,如果你想以 POST/ PUT請求的響應主體發送內容,也沒有人阻止你。
無論如何,讓我們再次嘗試創建相同的用戶。應該得到的HTTP響應顯示衝突。
4.更新用戶
發送一個HTTP PUT請求以更新的用戶。一併發送新的用戶的信息。
請注意,我們收到的響應體的這個時候。這是在控制器中的方法的實現發送。同樣,可以決定不發送更新信息的響應體,並只發送位置標頭(如創建)。
5. 刪除一個用戶
6. 刪除所有用戶
7. 用戶刪除後,驗證所有用戶
使用REST模板編寫REST客戶端
我們上面使用 Postman 是一個很好的客戶端測試 REST API 工具。但是,如果想從應用程序消耗基於REST的Web服務,需要一個REST客戶端的應用程序。其中最流行的 HTTP 客戶端就是 Apache HttpComponents HttpClient。 但在細節上使用這種訪問 REST 服務太低級。
Spring RestTemplate 可以來補救。 RestTemplate 提供對應於六個主要的 HTTP 方法,使許多調用RESTful服務只需要一行代碼,就可執行 REST最佳實踐的更高層次的方法。
下面顯示的是 HTTP 方法和相應 RestTemplate 方法來處理該類型的 HTTP 請求。
HTTP方法和相應的 RestTemplate 方法:
- HTTP GET : getForObject, getForEntity
- HTTP PUT : put(String url, Object request, String…urlVariables)
- HTTP DELETE : delete
- HTTP POST : postForLocation(String url, Object request, String… urlVariables), postForObject(String url, Object request, Class responseType, String… uriVariables)
- HTTP HEAD : headForHeaders(String url, String… urlVariables)
- HTTP OPTIONS : optionsForAllow(String url, String… urlVariables)
- HTTP PATCH and others : exchange execute
自定義REST客戶端,消費前面創建的 REST 服務。
package com.yiibai.springmvc;
import java.net.URI;
import java.util.LinkedHashMap;
import java.util.List;
import org.springframework.web.client.RestTemplate;
import com.yiibai.springmvc.model.User;
public class SpringRestTestClient {
public static final String REST_SERVICE_URI = "http://localhost:8080/Spring4MVCCRUDRestService";
/* GET */
@SuppressWarnings("unchecked")
private static void listAllUsers(){
System.out.println("Testing listAllUsers API-----------");
RestTemplate restTemplate = new RestTemplate();
List<LinkedHashMap<String, Object>> usersMap = restTemplate.getForObject(REST_SERVICE_URI+"/user/", List.class);
if(usersMap!=null){
for(LinkedHashMap<String, Object> map : usersMap){
System.out.println("User : id="+map.get("id")+", Name="+map.get("name")+", Age="+map.get("age")+", Salary="+map.get("salary"));;
}
}else{
System.out.println("No user exist----------");
}
}
/* GET */
private static void getUser(){
System.out.println("Testing getUser API----------");
RestTemplate restTemplate = new RestTemplate();
User user = restTemplate.getForObject(REST_SERVICE_URI+"/user/1", User.class);
System.out.println(user);
}
/* POST */
private static void createUser() {
System.out.println("Testing create User API----------");
RestTemplate restTemplate = new RestTemplate();
User user = new User(0,"Sarah",51,134);
URI uri = restTemplate.postForLocation(REST_SERVICE_URI+"/user/", user, User.class);
System.out.println("Location : "+uri.toASCIIString());
}
/* PUT */
private static void updateUser() {
System.out.println("Testing update User API----------");
RestTemplate restTemplate = new RestTemplate();
User user = new User(1,"Tomy",33, 70000);
restTemplate.put(REST_SERVICE_URI+"/user/1", user);
System.out.println(user);
}
/* DELETE */
private static void deleteUser() {
System.out.println("Testing delete User API----------");
RestTemplate restTemplate = new RestTemplate();
restTemplate.delete(REST_SERVICE_URI+"/user/3");
}
/* DELETE */
private static void deleteAllUsers() {
System.out.println("Testing all delete Users API----------");
RestTemplate restTemplate = new RestTemplate();
restTemplate.delete(REST_SERVICE_URI+"/user/");
}
public static void main(String args[]){
listAllUsers();
getUser();
createUser();
listAllUsers();
updateUser();
listAllUsers();
deleteUser();
listAllUsers();
deleteAllUsers();
listAllUsers();
}
}
重新啓動服務器(在我們的例子中,在服務器端的數據是固定的)。上面的程序運行。
從上面的客戶端程序輸出
Testing listAllUsers API-----------
User : id=1, Name=Sam, Age=30, Salary=70000.0
User : id=2, Name=Tom, Age=40, Salary=50000.0
User : id=3, Name=Jerome, Age=45, Salary=30000.0
User : id=4, Name=Silvia, Age=50, Salary=40000.0
Testing getUser API----------
User \[id=1, name=Sam, age=30, salary=70000.0\]
Testing create User API----------
Location : http://localhost:8080/Spring4MVCCRUDRestService/user/5
Testing listAllUsers API-----------
User : id=1, Name=Sam, Age=30, Salary=70000.0
User : id=2, Name=Tom, Age=40, Salary=50000.0
User : id=3, Name=Jerome, Age=45, Salary=30000.0
User : id=4, Name=Silvia, Age=50, Salary=40000.0
User : id=5, Name=Sarah, Age=51, Salary=134.0
Testing update User API----------
User \[id=1, name=Tomy, age=33, salary=70000.0\]
Testing listAllUsers API-----------
User : id=1, Name=Tomy, Age=33, Salary=70000.0
User : id=2, Name=Tom, Age=40, Salary=50000.0
User : id=3, Name=Jerome, Age=45, Salary=30000.0
User : id=4, Name=Silvia, Age=50, Salary=40000.0
User : id=5, Name=Sarah, Age=51, Salary=134.0
Testing delete User API----------
Testing listAllUsers API-----------
User : id=1, Name=Tomy, Age=33, Salary=70000.0
User : id=2, Name=Tom, Age=40, Salary=50000.0
User : id=4, Name=Silvia, Age=50, Salary=40000.0
User : id=5, Name=Sarah, Age=51, Salary=134.0
Testing all delete Users API----------
Testing listAllUsers API-----------
No user exist----------
完整的實例
工程結構
聲明項目的依賴關係
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4\_0\_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.yiibai.springmvc</groupId>
<artifactId>Spring4MVCCRUDRestService</artifactId>
<packaging>war</packaging>
<version>1.0.0</version>
<name>Spring4MVCCRUDRestService Maven Webapp</name>
<properties>
<springframework.version>4.2.0.RELEASE</springframework.version>
<jackson.version>2.5.3</jackson.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${springframework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-tx</artifactId>
<version>${springframework.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.4</version>
<configuration>
<warSourceDirectory>src/main/webapp</warSourceDirectory>
<warName>Spring4MVCCRUDRestService</warName>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
</plugins>
</pluginManagement>
<finalName>Spring4MVCCRUDRestService</finalName>
</build>
</project>
User Service
package com.yiibai.springmvc.service;
import java.util.List;
import com.yiibai.springmvc.model.User;
public interface UserService {
User findById(long id);
User findByName(String name);
void saveUser(User user);
void updateUser(User user);
void deleteUserById(long id);
List<User> findAllUsers();
void deleteAllUsers();
public boolean isUserExist(User user);
}
package com.yiibai.springmvc.service;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.yiibai.springmvc.model.User;
@Service("userService")
@Transactional
public class UserServiceImpl implements UserService{
private static final AtomicLong counter = new AtomicLong();
private static List<User> users;
static{
users= populateDummyUsers();
}
public List<User> findAllUsers() {
return users;
}
public User findById(long id) {
for(User user : users){
if(user.getId() == id){
return user;
}
}
return null;
}
public User findByName(String name) {
for(User user : users){
if(user.getName().equalsIgnoreCase(name)){
return user;
}
}
return null;
}
public void saveUser(User user) {
user.setId(counter.incrementAndGet());
users.add(user);
}
public void updateUser(User user) {
int index = users.indexOf(user);
users.set(index, user);
}
public void deleteUserById(long id) {
for (Iterator<User> iterator = users.iterator(); iterator.hasNext(); ) {
User user = iterator.next();
if (user.getId() == id) {
iterator.remove();
}
}
}
public boolean isUserExist(User user) {
return findByName(user.getName())!=null;
}
private static List<User> populateDummyUsers(){
List<User> users = new ArrayList<User>();
users.add(new User(counter.incrementAndGet(),"Sam",30, 70000));
users.add(new User(counter.incrementAndGet(),"Tom",40, 50000));
users.add(new User(counter.incrementAndGet(),"Jerome",45, 30000));
users.add(new User(counter.incrementAndGet(),"Silvia",50, 40000));
return users;
}
public void deleteAllUsers() {
users.clear();
}
}
Model class
package com.yiibai.springmvc.model;
public class User {
private long id;
private String name;
private int age;
private double salary;
public User(){
id=0;
}
public User(long id, String name, int age, double salary){
this.id = id;
this.name = name;
this.age = age;
this.salary = salary;
}
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
public double getSalary() {
return salary;
}
public void setSalary(double salary) {
this.salary = salary;
}
@Override
public int hashCode() {
final int prime = 31;
int result = 1;
result = prime * result + (int) (id ^ (id >>> 32));
return result;
}
@Override
public boolean equals(Object obj) {
if (this == obj)
return true;
if (obj == null)
return false;
if (getClass() != obj.getClass())
return false;
User other = (User) obj;
if (id != other.id)
return false;
return true;
}
@Override
public String toString() {
return "User [id=" + id + ", name=" + name + ", age=" + age
+ ", salary=" + salary + "]";
}
}
Configuration class
package com.yiibai.springmvc.configuration;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.yiibai.springmvc")
public class HelloWorldConfiguration {
}
Initialization Class
package com.yiibai.springmvc.configuration;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;
public class HelloWorldInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return new Class[] { HelloWorldConfiguration.class };
}
@Override
protected Class<?>[] getServletConfigClasses() {
return null;
}
@Override
protected String[] getServletMappings() {
return new String[] { "/" };
}
}
添加CORS支持REST API
當訪問 REST API 時,可能會面臨關於 同源策略的問題。
可能會出現這樣的錯誤:
」 No ‘Access-Control-Allow-Origin’ 的頭存在於所請求的資源。 Origin ‘http://127.0.0.1:8080′ is therefore not allowed access.」 OR」 XMLHttpRequest cannot load http://abc.com/bla. Origin http://localhost:12345 is not allowed by Access-Control-Allow-Origin.」 are common in such case.
解決辦法是跨域資源共享。基本上,在服務器端,我們可以返回更多的CORS系統的訪問控制頭在響應中,這將最終允許進一步域間的通信。
藉助於Spring,我們可以寫一個簡單的過濾器,並將這些 CORS 特定的頭文件添加到每一個響應中。
package com.yiibai.springmvc.configuration;
import java.io.IOException;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletResponse;
public class CORSFilter implements Filter {
public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {
System.out.println("Filtering on...........................................................");
HttpServletResponse response = (HttpServletResponse) res;
response.setHeader("Access-Control-Allow-Origin", "*");
response.setHeader("Access-Control-Allow-Methods", "POST, GET, PUT, OPTIONS, DELETE");
response.setHeader("Access-Control-Max-Age", "3600");
response.setHeader("Access-Control-Allow-Headers", "x-requested-with");
chain.doFilter(req, res);
}
public void init(FilterConfig filterConfig) {}
public void destroy() {}
}
然後我們可以簡單地將其配置在我們的 Spring 配置如下所示:
package com.yiibai.springmvc.configuration;
import javax.servlet.Filter;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;
public class HelloWorldInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return new Class[] { HelloWorldConfiguration.class };
}
@Override
protected Class<?>[] getServletConfigClasses() {
return null;
}
@Override
protected String[] getServletMappings() {
return new String[] { "/" };
}
@Override
protected Filter[] getServletFilters() {
Filter [] singleton = { new CORSFilter()};
return singleton;
}
}
有了這兩個額外的步驟,客戶可以與您的 REST API進行通信而無需擔心跨域問題。
到些整個示例教程講解完成,包教不包會。有興趣的朋友可以下載代碼: http://pan.baidu.com/s/1dEjOnp3