Apache Wink User Guide Software Version: 0.1 The Apache Wink User Guide document is a broad scope document that provides detailed information about the Apache Wink 0.1 design and implementation. Apache Wink 0.1 User Guide Table of Contents Apache Wink User Guide............................................................. 1 Table of Contents ......................................................................... 2 List of Tables ............................................................................... 8 1. Introduction .......................................................................... 9 1.1.1. Important Note ................................................................................................... 9 1.2. Target Audience .................................................................................................... 10 1.3. JAX-RS Compliancy .............................................................................................. 10 2. Apache Wink Architecture ................................................... 11 2.1. Wink Runtime Architecture Overview .................................................................. 11 2.2. Request Processor ................................................................................................. 12 2.3. Deployment Configuration .................................................................................... 13 2.3.1. Customization ................................................................................................... 13 2.4. Handler Chains ..................................................................................................... 15 2.5. Registries .............................................................................................................. 15 2.5.1. Resources Registry ............................................................................................ 16 2.5.2. Providers Registry............................................................................................. 17 3. Registration and Configuration ............................................. 18 3.1. Simple Application ................................................................................................ 18 3.1.1. Specifying the Simple Application File Location .............................................. 19 3.2. Wink Application................................................................................................... 19 2 3.3. Dynamic Resources ............................................................................................... 20 3.3.1. Motivation ......................................................................................................... 20 3.3.2. Usage ................................................................................................................ 21 3.3.3. Scope ................................................................................................................. 21 3.4. Priorities................................................................................................................ 22 3.4.1. Resource Priorities ............................................................................................ 22 3.4.2. Provider Priorities............................................................................................. 22 3.5. Properties .............................................................................................................. 23 3.5.1. Custom Properties File Definition .................................................................... 25 3.6. Runtime Registration ............................................................................................ 26 3.7. Media-Type Mapping ............................................................................................ 26 3.7.1. Customizing Mappings ..................................................................................... 27 3.8. Alternative Shortcuts ............................................................................................ 27 3.8.1. Customizing Shortcuts ...................................................................................... 28 4. Link Builders ....................................................................... 29 4.1. Link Builders Overview ........................................................................................ 29 4.2. The “alt” Query Parameter ................................................................................... 29 4.3. System Links Builder ............................................................................................ 30 4.3.1. Example ............................................................................................................ 30 4.4. Single Link Builder ............................................................................................... 31 4.5. Generating Absolute or Relative Links ................................................................. 31 5. Assets ................................................................................ 32 5.1. Assets Overview .................................................................................................... 32 5.2. Lifecycle................................................................................................................. 34 5.2.1. Response Entity Asset ...................................................................................... 34 5.2.2. Request Entity Asset ........................................................................................ 34 3 Apache Wink 0.1 User Guide 5.3. Asset Entity Methods ............................................................................................ 35 5.3.1. Entity Producing Methods ................................................................................ 35 5.3.2. Entity Consuming Methods .............................................................................. 35 5.4. Parameters ............................................................................................................ 35 5.5. Return Type .......................................................................................................... 35 5.6. Exceptions ............................................................................................................. 36 5.7. Annotation Inheritance ......................................................................................... 36 5.8. Entity Method Matching ....................................................................................... 36 5.8.1. Request Entity Matching .................................................................................. 37 5.8.2. Response Entity Matching ................................................................................ 37 5.9. Asset Example ....................................................................................................... 38 6. Providers ............................................................................ 41 6.1. Scoping .................................................................................................................. 41 6.1.1. Prototype Example ............................................................................................ 41 6.1.2. Singleton Example 1 ......................................................................................... 42 6.1.3. Singleton Example 2 ......................................................................................... 42 6.2. Priority .................................................................................................................. 42 6.3. Out-of-the-Box Implementations .......................................................................... 43 6.3.1. Atom Providers ................................................................................................. 43 6.3.2. APP Providers ................................................................................................... 45 6.3.3. OpenSearch Provider ........................................................................................ 46 6.3.4. Json Providers ................................................................................................... 47 6.3.5. Asset Provider ................................................................................................... 48 6.3.6. HTML Providers ............................................................................................... 49 6.3.7. CSV Providers ................................................................................................... 50 4 7. Annotations ........................................................................ 51 7.1. @Workspace Annotation ....................................................................................... 51 7.1.1. @Workspace Annotation Example .................................................................... 52 7.2. @Asset Annotation ................................................................................................ 54 7.3. @Scope Annotation ................................................................................................ 55 7.3.1. Resource Example ............................................................................................. 55 7.3.2. Provider Example ............................................................................................. 56 7.4. @Parent Annotation .............................................................................................. 56 8. Resource