User guide (Engine)

Introduction

There are some common basic concepts that need to be introduced before starting with ODataJClient.

URI management

URIs are a key concept in the OData protocol specification, so you should be already aware of the elements below (full reference to URI syntax is also available):

1. Service Root and Path Prefix
2. Resource Path
3. Query Options

Many methods referenced below in the Examples section require an URI parameter; with ODataJClient two options are available for this purpose:

1. provide an URI value via plain String: URI.create("http://services.odata.org/OData/OData.svc/Products");
2. feature the provided ODataURIBuilder - see the Examples below for some sample usage.

Request / Response handling

Working with ODataJClient can be generally summarized as:

1. get an ODataRequest instance (for the required kind of request) via one of the provided Factory objects;
2. (optionally) use another Factory object to build the parameter(s) to pass to the request created above;
3. execute the request and obtain a specialized ODataResponse instance (generally, at this point the actual REST communication with remote OData service takes place);
4. inspect the response object and read the body into one of Java classes built to represent the OData model objects (entity, entity set, property, and so on - read more about OData abstract data model).

Content format

ODataJClient supports two serialization formats for OData model objects:

1. Atom / XML
2. application/atom+xml (for Entity and Entity Set)
3. application/xml (for any other model object)
4. JSON, in its three variants
5. No Metadata application/json;odatda=nometadata
6. Minimal Metadata application/json or application/json;odatda=minimalmetadata
7. Full Metadata application/json;odatda=fullmetadata

Any ODataRequest object allows the content format to be specified; when not specified, application/json;odatda=fullmetadata is the default set.

Examples

In the following, let testODataServiceRootURL be the String representation of your OData service root (http://services.odata.org/OData/OData.svc/ for example).

Metadata

1. Read and parse

Service Document

1. Read and parse

Retrieve

1. Entity
2. EntitySet
3. Property
4. Property value
5. Filter

Create

1. Entity
2. Media entity

Update

1. Entity
2. Media entity
3. Property

Delete

1. Generic sample

Batch

1. Sample

Invoke

1. GET with no parameters
2. GET with parameters
3. POST with no parameters, bound to an entity

Basic authentication

1. Sample usage