org.schedulesdirect.api

Class EpgClient

java.lang.Object

org.schedulesdirect.api.EpgClient

Direct Known Subclasses:

NetworkEpgClient, ZipEpgClient

public abstract class EpgClient
extends Object

An EpgClient provides access to Schedules Direct JSON feed data.

An EpgClient instance must be used in order to gain access to all of the other object types available in this API. Only an EpgClient object can be directly instantiated by classes outside of this package.

Author:

Derek Battams <derek@battams.ca>

Field Summary

Fields

Modifier and Type	Field and Description
static int	API_VERSION The Schedules Direct server API version this client implements.

Constructor Summary

Constructors

Constructor and Description
EpgClient(String userAgent) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	close() Close and free all resources associated with this client connection
abstract void	deleteMessage(Message msg) Acknowledge receipt of and delete a message object from the upstream provider.
protected abstract String	fetchChannelMapping(Lineup lineup) Fetch the channel mapping for the given Linup object
protected abstract InputStream	fetchLogoStream(Station station) Fetch a Station's logo object
protected abstract Program	fetchProgram(String progId) Fetch a single Program object
protected abstract Map<String,Program>	fetchPrograms(String[] progIds) Fetch multiple programs in batch.
protected abstract Airing[]	fetchSchedule(Station station) Fetch a single airing schedule for the given Station reference
protected abstract Map<Station,Airing[]>	fetchSchedules(Lineup lineup) Fetch multiple recording schedules in batch.
abstract Lineup	getLineupByUriPath(String path) Get the lineup for the given uri
abstract Lineup[]	getLineups() Provide all available lineups for the logged in user.
Lineup[]	getLineups(String location, String zip) Provide all available lineups for the given location.
abstract SystemStatus	getSystemStatus() Return details of the current state of the Schedules Direct system
static String	getUriPathForLineupId(String id) Given a lineup id, generate the full, absolute URI path for the lineup
String	getUserAgent() Return the current user agent string being submitted to the SD servers from this client.
abstract UserStatus	getUserStatus() Get the UserStatus object associated with this EpgClient connection
abstract void	purgeCache() Purge the client's object cache.
abstract void	purgeCache(Object obj) Purge a specific object from the client's cache.
abstract int	registerLineup(String path) Register the given lineup with the user's SD account
protected abstract Lineup[]	searchForLineups(String location, String zip) Provide all available lineups for the given location.
void	setUserAgent(String userAgent) Set the user agent for all HTTP requests submitted to the SD servers from this client.
abstract int	unregisterLineup(Lineup l) Unregister the lineup from the user's SD account
protected void	writeLogoToFile(Station station, File dest) Write a station's logo to a file

Methods inherited from class java.lang.Object

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

Field Detail

API_VERSION

public static final int API_VERSION

The Schedules Direct server API version this client implements.

See Also:

Constant Field Values

Constructor Detail

EpgClient

public EpgClient(String userAgent)

Constructor

Parameters:

userAgent - The user agent to pass along to all SD HTTP requests

Method Detail

getUriPathForLineupId

public static String getUriPathForLineupId(String id)

Given a lineup id, generate the full, absolute URI path for the lineup

Parameters:

id - The unique lineup

Returns:

The unique, absolute URI path for the lineup id

getLineups

public final Lineup[] getLineups(String location,
                  String zip)
                          throws IOException

Provide all available lineups for the given location.

Parameters:

location - The 3 letter ISO country code; must be a country supported by the service (USA, CAN, etc.)

zip - The zip/postal code to find headends for

Returns:

An array of Lineup objects representing all available Lineups for the given zip; never returns null, but may return an empty array

Throws:

InvalidZipCodeException - Thrown if the given zip/postal code is invalid

IOException - Thrown if there is any kind of IO error accessing the raw data feed

searchForLineups

protected abstract Lineup[] searchForLineups(String location,
                        String zip)
                                      throws IOException

Provide all available lineups for the given location.

Parameters:

location - The 3 letter ISO country code; must be a country supported by the service (USA, CAN, etc.)

zip - The zip/postal code to find headends for

Returns:

An array of Lineup objects representing all available headends for the given zip; never returns null, but may return an empty array

Throws:

IOException - Thrown if there is any kind of IO error accessing the raw data feed

getLineups

public abstract Lineup[] getLineups()
                             throws IOException

Provide all available lineups for the logged in user.

This method will only return those lineups that are configured in the user's Schedules Direct account. These are the only lineups to which the user is guaranteed to have access to listings data for.

Returns:

An array of Lineup objects, one for each lineup configured in the user's Schedules Direct account

Throws:

IOException - Thrown if there is any kind of IO error accessing the data feed

getLineupByUriPath

public abstract Lineup getLineupByUriPath(String path)
                                   throws IOException

Get the lineup for the given uri

NOTE:This method will only return objects registered to the user's account (or available in the local cache). This method will not construct a Lineup object and return it if you do not have access to the Lineup in question. In other words, you must register a lineup in your SD account before this method will return it.

Parameters:

path - The absolute path to access the lineup data from; appended to BASE_URL to form full URI to be accessed

Returns:

The Lineup instance for the given path or null if it could not be found

Throws:

IOException - Thrown if there is any kind of IO error accessing the raw data feed

getUserStatus

public abstract UserStatus getUserStatus()
                                  throws IOException

Get the UserStatus object associated with this EpgClient connection

Returns:

The UserStatus object associated with this EpgClient instance

Throws:

IOException - Thrown if there is any kind of IO error accessing the raw data feed

setUserAgent

public void setUserAgent(String userAgent)

Set the user agent for all HTTP requests submitted to the SD servers from this client.

A default agent string is generated if not set.

Parameters:

userAgent - The user agent string to use for all HTTP requests to the SD servers

getUserAgent

public String getUserAgent()

Return the current user agent string being submitted to the SD servers from this client.

Returns:

The current user agent string

close

public abstract void close()
                    throws IOException

Close and free all resources associated with this client connection

Throws:

IOException - On any IO error

fetchSchedule

protected abstract Airing[] fetchSchedule(Station station)
                                   throws IOException

Fetch a single airing schedule for the given Station reference

Parameters:

station - The station to fetch the airing schedule for

Returns:

An array of Airing objects representing the airing schedule for the given Station; empty array if schedule data isn't available

Throws:

IOException - Thrown on any IO error accessing the schedule data

fetchChannelMapping

protected abstract String fetchChannelMapping(Lineup lineup)
                                       throws IOException

Fetch the channel mapping for the given Linup object

Parameters:

lineup - The lineup to fetch channel mappings for

Returns:

The JSON encoded response received from upstream

Throws:

IOException - On any IO error

fetchLogoStream

protected abstract InputStream fetchLogoStream(Station station)
                                        throws IOException

Fetch a Station's logo object

Parameters:

station - The station whose logo is to be fetched

Returns:

An InputStream containing the station's logo or null if one isn't available or an error occurred

Throws:

IOException - Thrown on any IO error

writeLogoToFile

protected void writeLogoToFile(Station station,
                   File dest)
                        throws IOException

Write a station's logo to a file

Parameters:

station - The station whose logo is to be written to file

dest - The destination of the write

Throws:

IOException - Thrown on any IO error

fetchProgram

protected abstract Program fetchProgram(String progId)
                                 throws IOException

Fetch a single Program object

Parameters:

progId - The program id to fetch

Returns:

The Program instance for the given program id or null if unavailable

Throws:

IOException - Thrown on any IO error accessing the data

fetchSchedules

protected abstract Map<Station,Airing[]> fetchSchedules(Lineup lineup)
                                                 throws IOException

Fetch multiple recording schedules in batch.

This method is preferred to fetchSchedule() as it will grab multiple schedules much more efficiently. Use this when ever you can.

Parameters:

lineup - The Lineup object to download schedules for

Returns:

A Map of Airing arrays, the key is the Station id, the value is that station's airing schedule

Throws:

IOException - In case of any IO error accessing the data

fetchPrograms

protected abstract Map<String,Program> fetchPrograms(String[] progIds)
                                              throws IOException

Fetch multiple programs in batch.

This method is preferred to fetchProgram() as it will grab multiple programs much more efficiently. Use this when ever you can.

Parameters:

progIds - An array of program ids to fetch

Returns:

A Map of fetched programs; the key is the progId and the value is the Program instance

Throws:

IOException - On any IO error accessing the data

purgeCache

public abstract void purgeCache()

Purge the client's object cache. This will force the client to reload all objects from their source.

purgeCache

public abstract void purgeCache(Object obj)

Purge a specific object from the client's cache. Accessing this object from this client after the purge will force the object to be reloaded from the client's upstream source.

Parameters:

obj - The object to purge from the client's local cache

deleteMessage

public abstract void deleteMessage(Message msg)
                            throws IOException

Acknowledge receipt of and delete a message object from the upstream provider.

Optional operation

Parameters:

msg - The message object to be deleted

Throws:

IOException - In case of any IO error upstream

getSystemStatus

public abstract SystemStatus getSystemStatus()
                                      throws IOException

Return details of the current state of the Schedules Direct system

Returns:

The current SD system status

Throws:

IOException - In case of any errors obtaining the status info

registerLineup

public abstract int registerLineup(String path)
                            throws IOException

Register the given lineup with the user's SD account

Optional operation

Parameters:

path - The full, absolute URI of the lineup to register; perhaps grab this value from EpgClient.getUriPathForLineupId()

Returns:

The number of register/unregister calls the user has remaining for today

Throws:

IOException - On any IO error

UnsupportedOperationException - If the client type doesn't support the operation

unregisterLineup

public abstract int unregisterLineup(Lineup l)
                              throws IOException

Unregister the lineup from the user's SD account

Optional operation

Parameters:

l - The linup to unregister from the user's account

Returns:

The number of register/unregister calls the user has remaining for today

Throws:

IOException - On any IO error

UnsupportedOperationException - If the client type doesn't support the operation