com.lightdev.lib.holiday.client
Class HolidayClient

java.lang.Object
  com.lightdev.lib.holiday.client.HolidayClient

public class HolidayClient
extends Object

Major element of the HolidayClient API to access the World Holiday Calendar Service.

Every instance of a HolidayClient object represents one session with the Light Development World Holiday Calendar Service. Class HolidayClient makes available all methods that other applications can use to interact with the service.

It can be used as follows:

 import java.text.SimpleDateFormat;
 import java.util.Calendar;
 import java.util.GregorianCalendar;

 import com.lightdev.app.trec.client.Client;
 import com.lightdev.lib.holiday.client.HolidayClient;
 import com.lightdev.lib.holiday.client.YearEvent;

 public class HolidayClientSample {
  public HolidayClientSample() {
    super();
  }
  public static void main(String[] args) {
    SimpleDateFormat sdf = new SimpleDateFormat("MM/dd/yyyy");
    HolidayClient holidayClient = new HolidayClient();
    try {
      holidayClient.login(
          "https://secure.lightdev.com/sec/apps", 
          "", 
          0, 
          true, 
          Client.DEFAULT_AUTHORIZER, 
          "demo", 
          "demo");
      //
      // region id and property are hard wired in the following code for demonstration 
      // purposes. Typically region ids and property ids are determined by methods 
      // getRegions and getProperties respectively before calling method getEventList.
      //
      String region_id_germany = "2";
      String property_id_all = "9";
      //
      // the demo user is entitled to view all observances in the year previous to the 
      // current year as well as observances in the current year until the current 
      // month (i.e. no future observances except for future days of the current month)
      //
      GregorianCalendar now = new GregorianCalendar();
      int previousYear = now.get(Calendar.YEAR) - 1;
      YearEvent[] events = holidayClient.getEventList(
          previousYear, property_id_all, region_id_germany, true, true, true, null);
      for(int i = 0; i < events.length; i++) {
        String eventName = events[i].toString();
        Integer id = (Integer) events[i].getId();
        GregorianCalendar[] dates = events[i].getDates();
        System.out.println("occurrences in year 2005 for " + id + " " + eventName + ":");
        for(int k = 0; k < dates.length; k++) {
          GregorianCalendar c = dates[k];
          System.out.println("     " + sdf.format(c.getTime()));
        }
      }
      holidayClient.logout(Client.DEFAULT_AUTHORIZER);
    }
    catch (Throwable e) {
      e.printStackTrace();
    }
  }
}

 

Please note that the classes required via imports shown above are all included in the HolidayClient API distribution package.

Version:

1, 09.05.2006

Author:

Ulrich Hilger, Light Development, http://www.lightdev.com, info@lightdev.com, published under the terms and conditions of the BSD License, for details see file license.txt in the distribution package of this software

Constructor Summary

HolidayClient()
create a new instance of a HolidayClient object

Method Summary

Object	deserialize(byte[] bytes) deserialize a byte array received from the server back to an object
Vector<HierarchicalItem>	getChildRegions(int regionId) get all regions that are children of a region with the given id
Client	getClient() get the TREC client object used to communicate with the server
YearEvent[]	getEventList(int year, String propertyId, String regionId, boolean includeParents, boolean includeChildren, boolean exWorld, AsyncCallback listener) get an array of events matching a given filter criteria
String[]	getEventTexts(int eventId, AsyncCallback listener) get texts describing an event
ServerAddress	getPreferredServer() get the address of the preferred server
Property[]	getProperties() get all properties
HierarchicalItem	getRegion(int regionId) get the region with a given id
Vector<HierarchicalItem>	getRegions() get all regions
Vector<HierarchicalItem>	getRootRegions() get all regions that have no parent region
boolean	isLoggedIn() determine whether or not this HolidayClient is logged in to the Light Development World Holiday Calendar Service
String	login(String url, String proxyUrl, int proxyPort, boolean encrypted, String agentName, String userId, String pw) login to the World Holiday Calendar Service
void	logout(String agentName) logout from current session.
byte[]	serialize(Object obj) serialize an object to a byte array
void	setPreferredServer(ServerAddress sa) set the preferred server address

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HolidayClient

public HolidayClient()

create a new instance of a HolidayClient object

Method Detail

login

public String login(String url,
                    String proxyUrl,
                    int proxyPort,
                    boolean encrypted,
                    String agentName,
                    String userId,
                    String pw)
             throws Throwable

login to the World Holiday Calendar Service

Parameters:

url - server URL, https://secure.lightdev.com/sec/apps at the time this version was created

proxyUrl - url of proxy server to use, set to "" when no proxy is to be used

proxyPort - port number of proxy server to use, set to 0 when no proxy is to be used

encrypted - true, when server at given url communicates via SSL, false if not

agentName - name of agent to use for authentication, typically Client.DEFAULT_AUTHORIZER

userId - id of user to login

pw - password of user to login

Returns:

the session id of logged in user

Throws:

Throwable - when login attempt failed, e.g. due to wrong user id or password or when an other error occurred that led to login failure

isLoggedIn

public boolean isLoggedIn()

determine whether or not this HolidayClient is logged in to the Light Development World Holiday Calendar Service

Returns:

treu, when logged in, false if not

logout

public void logout(String agentName)
            throws Throwable

logout from current session.

This method assumes that a user logged in previously. The Holiday Client API caches a logged in user in an own session until this logout method is called or until the session is inactive for a certain period of time.

Parameters:

agentName - name of agent to use for authentication, typically Client.DEFAULT_AUTHORIZER

Throws:

Throwable - e.g. when logout is called although no user is currently logged in

getRegion

public HierarchicalItem getRegion(int regionId)

get the region with a given id

Parameters:

regionId - the id to get the region for

Returns:

the region with the given id

getRootRegions

public Vector<HierarchicalItem> getRootRegions()

get all regions that have no parent region

Returns:

all root regions

getChildRegions

public Vector<HierarchicalItem> getChildRegions(int regionId)

get all regions that are children of a region with the given id

Parameters:

regionId - id of region to get children of

Returns:

child regions of region with the given id

getEventTexts

public String[] getEventTexts(int eventId,
                              AsyncCallback listener)
                       throws Throwable

get texts describing an event

Parameters:

eventId - id of event to get texts for

Returns:

a String array of texts, 0=occurence description, 1=event description

Throws:

Exception

Throwable

getEventList

public YearEvent[] getEventList(int year,
                                String propertyId,
                                String regionId,
                                boolean includeParents,
                                boolean includeChildren,
                                boolean exWorld,
                                AsyncCallback listener)
                         throws Throwable

get an array of events matching a given filter criteria

Parameters:

year - the year to return occurrences for

propertyId - id of property to get events for, e.g. legal/public/bank holiday, hindu holiday, etc.

regionId - id of region to get events for, e.g. 9 for Germany, etc.

includeParents - true when events associated to parent regions should be returned too

includeChildren - true when events associated to child regions should be returned too

exWorld - true when world should be excluded from parent regions

listener - AsyncCallback object that should handle results of an asynchronous call, null if method should be executed synchronously, i.e. blocking until it returns

Returns:

an array of events matching the given filter criteria when executed synchronously, null when executed asnychronously

Throws:

Throwable

getRegions

public Vector<HierarchicalItem> getRegions()
                                    throws Throwable

get all regions

Returns:

all the regions

Throws:

Throwable

getProperties

public Property[] getProperties()
                         throws Throwable

get all properties

Returns:

all the properties

Throws:

Throwable

getClient

public Client getClient()

get the TREC client object used to communicate with the server

Returns:

the TREC client

deserialize

public Object deserialize(byte[] bytes)
                   throws IOException,
                          ClassNotFoundException

deserialize a byte array received from the server back to an object

Parameters:

bytes - the byte array to transform

Returns:

the object transformed from the byte array

Throws:

IOException

ClassNotFoundException

serialize

public byte[] serialize(Object obj)

serialize an object to a byte array

Parameters:

obj - the object to transform

Returns:

the byte array for the given object

getPreferredServer

public ServerAddress getPreferredServer()

get the address of the preferred server

Returns:

address of server

setPreferredServer

public void setPreferredServer(ServerAddress sa)

set the preferred server address

Parameters:

sa - server address to set