Restlet Framework - User Guide - Version 2.0
Total Page:16
File Type:pdf, Size:1020Kb
Restlet Framework - User Guide - Version 2.0 December 6, 2010 Table of Contents 1 Welcome to the Restlet Framework ! 20 1.1 Introduction 20 1.2 Overview 20 1.3 Community support 21 1.4 Private support 21 1.5 Features 21 1.5.1 Introduction 21 1.5.2 Client and server side 21 1.5.3 Servlet compatible 21 1.5.4 Complete Web server 21 1.5.5 Presentation and persistence agnostic 22 1.5.6 Multiple editions 22 1.5.7 Native REST support 22 1.5.8 Available Connectors 23 1.5.9 Available Representations 23 1.5.10 Flexible configuration 23 1.5.11 Security 24 1.5.12 Scalability 24 1.5.13 Upcoming features 24 1.6 What's new in version 2.0 24 1.6.1 Introduction 24 1.6.2 API improvements 25 1.6.2.1 Packages restructuring 25 1.6.2.2 Root package 25 1.6.2.3 Data package 26 Restlet Framework - User Guide - Version 2.0 1 1.6.2.4 Representation package 26 1.6.2.5 Resource package 26 1.6.2.6 Routing package 28 1.6.2.7 Security package 28 1.6.2.8 Service package 28 1.6.3 Connectors 28 1.6.3.1 Content negotiation 28 1.6.3.2 CLAP client 28 1.6.3.3 Internal HTTP connectors 28 1.6.3.4 Internal JAR and ZIP clients 29 1.6.3.5 RIAP connectors 29 1.6.4 Extensions 29 1.6.4.1 Crypto extension 29 1.6.4.2 FreeMarker extension 29 1.6.4.3 GWT extension (server-side) 29 1.6.4.4 HTTP Client extension (Apache) 29 1.6.4.5 JAAS extension 29 1.6.4.6 Jackson extension 30 1.6.4.7 JAX-RS extension 30 1.6.4.8 Jetty extension 30 1.6.4.9 Lucene extension 30 1.6.4.10 Net extension 30 1.6.4.11 Netty extension 30 1.6.4.12 OData extension 30 1.6.4.13 RDF extension 30 1.6.4.14 ROME extension 31 1.6.4.15 Servlet extension 31 1.6.4.16 SLF4J extension 31 1.6.4.17 Spring extension 31 1.6.4.18 XML extension 31 1.6.4.19 XStream extension 31 1.6.5 Editions 32 1.6.5.1 Introduction 32 1.6.5.2 Java SE edition (JSE) 32 1.6.5.3 Java EE edition (JEE) 32 Restlet Framework - User Guide - Version 2.0 2 1.6.5.4 Google App Engine edition (GAE) 32 1.6.5.5 Google Web Toolkit edition (GWT) 32 1.6.5.6 Android edition 32 1.6.6 Misc 32 1.6.6.1 Enhanced Maven support 32 1.6.6.2 Licensing changes 33 1.6.6.3 OAuth extension 33 1.6.7 Migration guide from version 1.1 to 2.0 33 1.6.7.1 Introduction 33 1.6.7.2 Adjust your imports 33 1.6.7.3 Deprecated API features 33 1.7 First steps 34 1.7.1 Introduction 34 1.7.2 First server 34 1.7.2.1 Introduction 34 1.7.3 First client 34 1.7.3.1 Introduction 34 1.7.4 First application 35 1.7.4.1 Introduction 35 1.7.4.2 Table of contents 35 1.7.4.3 Requirements 36 1.7.4.4 Scenario 36 1.7.4.5 Archive content 36 1.7.4.6 Common classes 37 1.7.4.7 GAE server part 37 1.7.4.8 GWT client part 38 1.7.4.9 Android client part 39 1.7.4.10 Java SE client 40 1.8 Architecture 41 1.8.1 Introduction 41 1.8.2 Overview of a REST architecture 41 1.8.3 Overview of a Restlet architecture 42 1.8.4 Presentation layer 42 1.8.4.1 Introduction 42 1.8.4.2 Description 43 Restlet Framework - User Guide - Version 2.0 3 1.8.5 Persistence layer 43 1.8.5.1 Introduction 43 1.8.5.2 Description 43 1.9 Getting started 43 1.9.1 Getting started with Eclipse IDE 44 1.9.1.1 Introduction 44 1.9.2 Getting started with Maven 44 1.9.2.1 Introduction 44 1.9.2.2 Public repository configuration 44 1.9.2.3 Available artifacts 45 1.9.2.4 Sample dependencies declaration 47 1.9.3 Getting Started with Maven and Spring 47 1.9.3.1 Overview 47 1.9.3.2 Prerequisites 47 1.9.3.3 The Steps 48 1.9.3.4 Resources 53 1.9.4 Debugging tools 53 1.9.4.1 Introduction 53 1.9.4.2 Tools 53 2 Restlet API 56 2.1 Introduction 56 2.2 API Introduction 57 2.2.1 Mapping HTTP headers 57 2.2.1.1 Introduction 57 2.2.1.2 From HTTP headers to Restlet API 57 2.2.1.3 Appendix 63 2.3 Base package 63 2.3.1 Introduction 63 2.3.2 Connectors 63 2.3.2.1 Introduction 63 2.3.2.2 Add a connector to your application 63 2.3.2.3 Configuration 63 2.3.2.4 List of available connectors 64 Restlet Framework - User Guide - Version 2.0 4 2.4 Data package 65 2.4.1 Introduction 65 2.4.2 Getting parameter values 66 2.4.2.1 Introduction 66 2.4.2.2 Getting values from a web form 66 2.4.2.3 Getting values from a query 66 2.4.2.4 Getting values from the cookies 66 2.5 Representation package 66 2.5.1 Introduction 66 2.6 Resource package 67 2.6.1 Introduction 67 2.6.2 Client resources 67 2.6.2.1 Introduction 67 2.6.2.2 Automatic conversion 67 2.6.2.3 Leveraging annotations 68 2.6.2.4 Consuming response entities 69 2.6.3 Server resources 70 2.7 Routing package 70 2.7.1 Introduction 70 2.7.2 Default configuration 70 2.7.2.1 Matching mode 71 2.7.2.2 Routing and queries 71 2.7.2.3 Routing mode 71 2.7.2.4 Matching of template variables 71 2.7.3 Tuning the routing 72 2.7.3.1 Matching mode 72 2.7.3.2 Routing and queries 72 2.7.3.3 Matching of template variables 72 2.7.4 Tutorial 73 2.7.4.1 Introduction 73 2.7.5 URI rewriting and redirection 74 2.7.5.1 Introduction 74 2.7.6 Routers and hierarchical URIs 74 2.7.6.1 Introduction 74 Restlet Framework - User Guide - Version 2.0 5 2.7.7 Extracting attributes 76 2.7.7.1 Introduction 76 2.8 Security package 77 2.8.1 Introduction 77 2.8.2 Tutorial 77 2.8.3 Restlet API 78 2.8.4 Restlet Engine 80 2.8.5 Extensions 80 2.8.6 Confidentiality 80 2.8.7 Authentication 81 2.8.8 Coarsed grained authorization 82 2.8.9 Fine grained authorization 82 2.8.10 Potential vulnerabilities 82 2.8.11 Sample code 83 2.8.12 Authentication 83 2.8.12.1 Introduction 83 2.8.12.2 HTTP Basic authentication 83 2.8.12.3 HTTP Digest authentication 85 2.8.12.4 NTLM authentication 87 2.8.13 Authorization 88 2.8.13.1 Introduction 88 2.8.13.2 Coarse-grained authorization 88 2.8.13.3 Fine-grained authorization 88 2.8.13.4 Middle-grained authorization 88 2.8.14 Configuring HTTPS 88 2.9 Service package 93 2.9.1 Introduction 93 2.9.2 Component services 93 2.9.3 Application services 94 2.9.4 Connector service 94 2.9.4.1 Introduction 94 2.9.5 ConverterService 94 2.9.5.1 Introduction 94 2.9.5.2 Description 94 2.9.5.3 Available converters 95 Restlet Framework - User Guide - Version 2.0 6 2.9.6 Decoder service 97 2.9.6.1 Introduction 97 2.9.7 Log service 97 2.9.7.1 Introduction 97 2.9.7.2 Default access log format 98 2.9.8 Metadata service 98 2.9.8.1 Introduction 98 2.9.9 Range service 98 2.9.9.1 Introduction 98 2.9.10 Status service 99 2.9.10.1 Introduction 99 2.9.10.2 Display error pages 99 2.9.11 Task service 99 2.9.11.1 Introduction 99 2.9.12 Tunnel service 100 2.9.12.1 Introduction 100 2.10 Util package 101 2.10.1 Introduction 101 3 Restlet Editions 105 3.1 Introduction 105 3.2 Restlet edition for Java SE 105 3.2.1 Introduction 105 3.2.2 Getting started 105 3.2.2.1 What do I need? 106 3.2.2.2 The "hello, world" application 106 3.2.2.3 Run as a standalone Java application 106 3.2.2.4 Conclusion 107 3.2.3 Logging 107 3.2.3.1 Introduction 107 3.2.3.2 Logger names 108 3.2.3.3 Sample configuration 109 3.2.3.4 Bridges to alternative logging mechanisms 112 3.2.3.5 Additional resources 113 Restlet Framework - User Guide - Version 2.0 7 3.3 Restlet edition for Java EE 113 3.3.1 Introduction 113 3.3.2 Getting started 113 3.3.2.1 What do I need? 113 3.3.2.2 The "hello, world" application 113 3.3.2.3 Run in a Servlet container 114 3.3.2.4 Run as a standalone Java application 115 3.3.2.5 Conclusion 115 3.3.3 Client connectors 116 3.3.3.1 Introduction 116 3.4 Restlet edition for Google App Engine 116 3.4.1 Introduction 116 3.4.2 Usage example 116 3.4.3 Javadocs 118 3.5 Restlet edition for Google Web Toolkit 118 3.5.1 Introduction 118 3.5.2 Description 118 3.5.3 Architecture flexibility 119 3.5.3.1 Introduction 119 3.5.3.2 GWT's idiomatic RPC approach 119 3.5.3.3 The client-side Restlet/GWT module 120 3.5.3.4 Restlet/GWT can work alongside GWT-RPC 121 3.5.3.5 Restlet, an ideal server side companion for Restlet-GWT 122 3.5.3.6 Integration with standalone Restlet connectors 123 3.5.4 Setting up a project 123 3.5.4.1 Client-side configuration 123 3.5.4.2 Server-side configuration 124 3.5.5 Invoking server side code 124 3.5.5.1 Description 124 3.5.6 Examples 125 3.5.6.1 Introduction 125 3.5.6.2 Description 126 3.5.7 Authenticating requests 127 3.5.7.1 Introduction 127 3.5.7.2 Authentication with the HTTP_BASIC scheme 127 Restlet Framework - User Guide - Version 2.0 8 3.5.7.3 Authentication with the HTTP_DIGEST scheme 128 3.5.8 Working with JSON 128 3.5.8.1 Description 128 3.5.9 Working with XML 129 3.5.9.1 Description 129 3.5.10 Tips and tricks 129 3.5.10.1 Responses with no entity 129 3.5.11 Deploy GWT sample application in Servlet container 130 3.5.11.1 Introduction 130 3.5.11.2 Set up the WAR file 130 3.6 Restlet edition for Android 131 3.6.1 Introduction 131 3.6.2 A Web server on a mobile phone 131 3.6.3 A Web client on a mobile phone 131 3.6.4 Specificities 131 3.6.5 Sample application 132 3.6.5.1 Introduction 132 3.6.5.2 Architecture 132 3.6.5.3 Screenshots 133 3.6.5.4 Implementation 133 4 Restlet Extensions 138 4.1 Introduction 138 4.2 Description 138 4.3 Distribution 138 4.4 Editions matrix 138 4.4.1 Introduction 138 4.4.2 Extensions availability 139 4.5 Atom extension 142 4.5.1 Introduction 142 4.5.2 Description 142 4.6 Crypto extension 142 4.6.1 Introduction 142 Restlet Framework - User Guide - Version 2.0 9 4.7 Apache FileUpload extension 142 4.7.1 Introduction 142 4.7.2 Description 143 4.7.3 Usage example 143 4.8 FreeMarker extension 144 4.8.1 Introduction 144 4.8.2 Description 145 4.9 Grizzly extension 145 4.9.1 Introduction 145 4.9.2 Description 145 4.10 GWT extension 145 4.10.1 Introduction 145 4.11 Apache HTTP Client extension 145 4.11.1 Introduction 145 4.11.2 Description 146 4.12 JAAS extension 146 4.12.1 Introduction 146 4.12.2 Authenticating with LDAP 146 4.13 Jackson extension 147 4.13.1