Click here to load reader

JAX-RS: Java API for RESTful Web Services ... JAX-RS: Java API for RESTful Web Services Version 2.1 Final Release July 13, 2017 Editors: Pavel Bucek Santiago Pericas-Geertsen Comments

  • View
    0

  • Download
    0

Embed Size (px)

Text of JAX-RS: Java API for RESTful Web Services ... JAX-RS: Java API for RESTful Web Services Version 2.1...

  • JAX-RS: Java™ API for RESTful Web Services

    Version 2.1 Final Release July 13, 2017

    Editors: Pavel Bucek

    Santiago Pericas-Geertsen

    Comments to: [email protected]

    Oracle Corporation 500 Oracle Parkway, Redwood Shores, CA 94065 USA.

  • ii JAX-RS July 13, 2017

  • Contents

    1 Introduction 1

    1.1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

    1.2 Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

    1.3 Non-Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

    1.4 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

    1.5 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

    1.6 Expert Group Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

    1.7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2 Applications 7

    2.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.2 Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.3 Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.3.1 Java SE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.3.2 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

    2.3.3 Other Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

    3 Resources 11

    3.1 Resource Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    3.1.1 Lifecycle and Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    3.1.2 Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    3.2 Fields and Bean Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

    3.3 Resource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    3.3.1 Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    3.3.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    3.3.3 Return Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    3.3.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

    July 13, 2017 JAX-RS iii

  • 3.3.5 HEAD and OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    3.4 URI Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    3.4.1 Sub Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    3.5 Declaring Media Type Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

    3.6 Annotation Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

    3.7 Matching Requests to Resource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.7.1 Request Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.7.2 Request Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.7.3 Converting URI Templates to Regular Expressions . . . . . . . . . . . . . . . . . . 24

    3.8 Determining the MediaType of Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

    4 Providers 27

    4.1 Lifecycle and Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.1.1 Automatic Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.1.2 Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.1.3 Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.2 Entity Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.2.1 Message Body Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.2.2 Message Body Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    4.2.3 Declaring Media Type Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . 30

    4.2.4 Standard Entity Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

    4.2.5 Transfer Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.2.6 Content Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.3 Context Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.3.1 Declaring Media Type Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.4 Exception Mapping Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    4.5 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    4.5.1 Server Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    4.5.2 Client Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    5 Client API 33

    5.1 Bootstrapping a Client Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

    5.2 Resource Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

    5.3 Client Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

    5.4 Typed Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

    iv JAX-RS July 13, 2017

  • 5.5 Invocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

    5.6 Configurable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

    5.6.1 Filters and Entity Interceptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

    5.7 Reactive Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

    5.7.1 Reactive API Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

    5.8 Executor Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

    6 Filters and Interceptors 39

    6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

    6.2 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

    6.3 Entity Interceptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

    6.4 Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

    6.5 Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

    6.5.1 Global Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

    6.5.2 Name Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

    6.5.3 Dynamic Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

    6.5.4 Binding in Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

    6.6 Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

    6.7 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

    6.7.1 Server Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

    6.7.2 Client Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

    7 Validation 47

    7.1 Constraint Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

    7.2 Annotations and Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

    7.3 Entity Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

    7.4 Default Validation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

    7.5 Annotation Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

    7.6 Validation and Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

    8 Asynchronous Processing 53

    8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

    8.2 Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

    8.2.1 AsyncResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

    8.2.2 CompletionStage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

    8.3 EJB Resource Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

    July 13, 2017 JAX-RS v

  • 8.4 Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

    9 Server-Sent Events 59

    9.1 Introduction . . . . . . . . . . . .

Search related