PUT and POST Methods

PUT and POST Methods

Overview

The HttpPutMethod, is an extension of the HttpPut class in HttpClient 4.x, to allow calendar specific settings to be applied. Similarly, HttpPostMethod is an extension of the HttpPost, for the same reasons.

NOTE: If you do not intend to do use PUT and POST methods with Calendar specific functionality, then just use the general classes, i.e. use HttpPut or HttpPost instead.

These two classes in their API’s are the similar, implementing method specific functionality of course.. Their constructors in general are of the form:

public HttpPutMethod(URI uri, CalendarRequest calendarRequest, CalendarOutputter calendarOutputter) { ... }

and

public HttpPostMethod(URI uri, CalendarRequest calendarRequest, CalendarOutputter calendarOutputter) { ... }

The two main things to note are these require a CalendarRequest object, and CalendarOutputterObjects.

• com.github.caldav4j.model.request.CalendarRequest: This object represents a marshalling object representing the parameters to be used along with PUT or POST. In essence it is a simple container class.
• net.fortuna.ical4j.data.CalendarOutputter: These are required to produce the String versions of the Calendar request.

CalendarRequest Objects

This object presents a collation of all the common Calendar based objects that can be accessed and set, through their own getters and setters.

Current list of properties is as follows:

• net.fortuna.ical4j.model.Calendar calendar : Calendar to be used as a PUT or POST request body
• Charset charset : Represents the character set of the Calendar to be used for the HTTP Request body. This defaults to Charset.defaultCharset() if none is provided, which is the JVM’s character set.
• Set<String> etags : Set of unique etags, defining the request. These according to RFC 2616 Section 14.19 or RFC 7232 Sec 2.3 represents the unique id referring to the object, at the current state. Note this has to be a quoted string, i.e. “ETAG-Value”
• boolean allEtags : Specify that all etags are accepted. This implies a value of * for the etag. Note: if allEtags is set and we also have some objects in etags, then allEtags value is given preference.
• boolean ifMatch : If true specfies that the etag should should be matched. This adds an If-Match header with those etags. For more info refer to the RFC 2616 Section 14.24.
• boolean ifNoneMatch : If true specfies that the etag should not be match. This adds an If--None-Match header with those etags. For more info refer to the RFC 2616 Section 14.26.

  Note: If ifMatch and ifNoneMatch are both set to true then, ifMatch value is given preference.

CalendarOutputter object

This object is necessary to set the Request body for the Http request. If one is using CalDAV4jMethodFactory for construction of the method objects, then setting the CalendarOutputter object is not needed and is done implicitly.

Examples

Creation of CalendarRequest objects

Note: For creation of Calendar objects, please refer to iCal4j’s documentation here and here

For more ways, refer to the javadocs of this object.

Ex 1

Calendar calendar = ...;

CalendarRequest cr = new CalendarRequest(calendar);

Ex 2

VEvent event = ...;
CalendarRequest cr = new CalendarRequest();
cr.setCalendar(event);

Ex 3

Calendar calendar = ...;

CalendarRequest cr = new CalendarRequest();
cr.setCalendar(calendar);
cr.setAllEtags(true);
cr.setCharset(Charset.forName("UTF-8"));

cr.addEtag("\"E2\""); // Quoted
cr.setIfMatch(true);
cr.setIfNoneMatch(true);

Ex 4

Calendar calendar = ...;
boolean allEtags = true, ifMatch = false, ifNoneMatch = True;

Set<String> etags = new HashSet<>();

etags.add("\"E2\""); // Quoted Etag

// All constructor args version.
// Note: If allEtags and etags are both set, then allEtags is given preference.
CalendarRequest cr = new CalendarRequest(calendar, Charset.forName("UTF-8"), etags, ifMatch, ifNoneMatch, allEtags);

// Alternate Version
CalendarRequest cr1 = new CalendarRequest(calendar, etags, ifMatch, ifNoneMatch);
cr1.setCharset(Charset.forName("UTF-8"));

// Alternate version for Matching all Etags

CalendarRequest cr2 = new CalendarRequest(calendar, ifMatch, ifNoneMatch, allEtags);
cr2.setCharset(Charset.forName("UTF-8"));

Creation of PUT and POST Methods

PUT

With CalDAV4jfactory

String uri = "http://example.com";
CalendarRequest cr = ... ;

CalDAV4JMethodFactory factory = new CalDAV4JMethodFactory();
HttpPutMethod method = factory.createPutMethod(uri, cr);

Without

String uri = "http://example.com";
CalendarRequest cr = ... ;
CalendarOutputter outputter = new CalendarOutputter(/* Custom params */);
		
HttpPutMethod method = new HttpPutMethod(uri, cr, outputter);

POST

Similarily the creation of this is the same.

With CalDAV4jfactory

String uri = "http://example.com";
CalendarRequest cr = ... ;

CalDAV4JMethodFactory factory = new CalDAV4JMethodFactory();
HttpPostMethod method = factory.createPostMethod(uri, cr);

Without

String uri = "http://example.com";
CalendarRequest cr = ... ;
CalendarOutputter outputter = new CalendarOutputter(/* Custom params */);
		
HttpPostMethod method = new HttpPostMethod(uri, cr, outputter);