org.schedulesdirect.api

Class ZipEpgClient

java.lang.Object

org.schedulesdirect.api.EpgClient

org.schedulesdirect.api.ZipEpgClient

public class ZipEpgClient
extends EpgClient

An implementation of EpgClient that uses a local zip file as its data source

The zip file to be used must follow a specific format and structure. Such a zip file can be generated by running the EPG Grabber application.

This implementation has two common uses:

1. For development and testing of this API, you can download a zip file of listings data and reuse it instead of constantly hitting the Schedules Direct servers.
2. For production, applications should always simply download a zip file once a day and reuse that zip file via this client implentation, which provides a simple form a caching.

Most every real world application should only be accessing EPG data via instances of this class. Apps should download their EPG data once a day using the sdjson grabber application then feeding that generated zip file into instances of this class to access the EPG data in their apps.

Author:

Derek Battams <derek@battams.ca>

Field Summary

Fields

Modifier and Type	Field and Description
static String	INVALID_FILE_CHARS Regex of invalid chars for file names in the zip
static String	LINEUPS_LIST The file containing all the lineups stored in this zip cache
static String	USER_DATA The file containing the user data for this zip cache (i.e.
static Charset	ZIP_CHARSET The default charset encoding used for all data in the generated zip file
static int	ZIP_VER The zip file version this grabber generates
static String	ZIP_VER_FILE Name of the file holding the zip file version number

Fields inherited from class org.schedulesdirect.api.EpgClient

API_VERSION

Constructor Summary

Constructors

Constructor and Description
ZipEpgClient(File zip) Constructor
ZipEpgClient(File zip, String baseUrl) Constructor
ZipEpgClient(Path zip) Constructor
ZipEpgClient(Path zip, String baseUrl) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close and free all resources associated with this client connection
void	deleteMessage(Message msg) Acknowledge receipt of and delete a message object from the upstream provider.
protected String	fetchChannelMapping(Lineup lineup) Fetch the channel mapping for the given Linup object
protected InputStream	fetchLogoStream(Station station) Fetch a Station's logo object
protected Program	fetchProgram(String progId) Fetch a single Program object
protected Map<String,Program>	fetchPrograms(String[] progIds) Fetch multiple programs in batch.
protected Airing[]	fetchSchedule(Station station) Fetch a single airing schedule for the given Station reference
protected Map<Station,Airing[]>	fetchSchedules(Lineup lineup) Fetch multiple recording schedules in batch.
protected void	finalize()
protected org.json.JSONObject	findMetadataForDevice(org.json.JSONArray metas, String dev) Find the metadata object for the given device name
Airing[]	findScheduleGap() Check all downloaded schedules for gaps in the airing schedules
Lineup	getLineupByUriPath(String path) Get the lineup for the given uri
Lineup[]	getLineups() Provide all available lineups for the logged in user.
SystemStatus	getSystemStatus() Return details of the current state of the Schedules Direct system
UserStatus	getUserStatus() Get the UserStatus object associated with this EpgClient connection
void	purgeCache() Purge the client's object cache.
void	purgeCache(Object obj) Purge a specific object from the client's cache.
int	registerLineup(String path) Register the given lineup with the user's SD account
static String	scrubFileName(String input) Scrub a file name, replacing invalid chars
protected Lineup[]	searchForLineups(String location, String zip) Provide all available lineups for the given location.
int	unregisterLineup(Lineup l) Unregister the lineup from the user's SD account

Methods inherited from class org.schedulesdirect.api.EpgClient

getBaseUrl, getLineups, getUriPathForLineupId, getUserAgent, setBaseUri, setUserAgent, writeLogoToFile

Methods inherited from class java.lang.Object

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

Field Detail

ZIP_VER_FILE

public static final String ZIP_VER_FILE

Name of the file holding the zip file version number

See Also:

Constant Field Values

ZIP_VER

public static final int ZIP_VER

The zip file version this grabber generates

See Also:

Constant Field Values

ZIP_CHARSET

public static final Charset ZIP_CHARSET

The default charset encoding used for all data in the generated zip file

LINEUPS_LIST

public static final String LINEUPS_LIST

The file containing all the lineups stored in this zip cache

See Also:

Constant Field Values

USER_DATA

public static final String USER_DATA

The file containing the user data for this zip cache (i.e. the user who generated the cache)

See Also:

Constant Field Values

INVALID_FILE_CHARS

public static final String INVALID_FILE_CHARS

Regex of invalid chars for file names in the zip

See Also:

Constant Field Values

Constructor Detail

ZipEpgClient

public ZipEpgClient(Path zip,
            String baseUrl)
             throws IOException

Constructor

Parameters:

zip - The zip path to be used as the data source for this client implementation

baseUrl - The base URL used to construct absolute URLs from relative URL data in the raw JSON

Throws:

IOException - Thrown on any IO error reading the zip file

ZipEpgClient

public ZipEpgClient(File zip,
            String baseUrl)
             throws IOException

Constructor

Parameters:

zip - The zip file to be used as the data source for this client implementation

baseUrl - The base URL used to construct absolute URLs from relative URL data in the raw JSON

Throws:

IOException - Thrown on any IO error reading the zip file

ZipEpgClient

public ZipEpgClient(Path zip)
             throws IOException

Constructor

Parameters:

zip - The zip path to be used as the data source for this client implementation

Throws:

IOException - Thrown on any IO error reading the zip file

ZipEpgClient

public ZipEpgClient(File zip)
             throws IOException

Constructor

Parameters:

zip - The zip file to be used as the data source for this client implementation

Throws:

IOException - Thrown on any IO error reading the zip file

Method Detail

scrubFileName

public static String scrubFileName(String input)

Scrub a file name, replacing invalid chars

Parameters:

input - The file name to scrub

Returns:

The scrubbed file name; suitable for use in the generated zip file

getUserStatus

public UserStatus getUserStatus()
                         throws IOException

Description copied from class: EpgClient

Get the UserStatus object associated with this EpgClient connection

Specified by:

getUserStatus in class EpgClient

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

close

public void close()
           throws IOException

Description copied from class: EpgClient

Close and free all resources associated with this client connection

Specified by:

close in class EpgClient

Throws:

IOException - On any IO error

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

fetchSchedule

protected Airing[] fetchSchedule(Station station)
                          throws IOException

Description copied from class: EpgClient

Fetch a single airing schedule for the given Station reference

Specified by:

fetchSchedule in class EpgClient

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

fetchProgram

protected Program fetchProgram(String progId)
                        throws IOException

Description copied from class: EpgClient

Fetch a single Program object

Specified by:

fetchProgram in class EpgClient

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 Map<Station,Airing[]> fetchSchedules(Lineup lineup)
                                        throws IOException

Description copied from class: EpgClient

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.

Specified by:

fetchSchedules in class EpgClient

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 Map<String,Program> fetchPrograms(String[] progIds)
                                     throws IOException

Description copied from class: EpgClient

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.

Specified by:

fetchPrograms in class EpgClient

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

findMetadataForDevice

protected org.json.JSONObject findMetadataForDevice(org.json.JSONArray metas,
                                        String dev)
                                             throws org.json.JSONException

Find the metadata object for the given device name

Parameters:

metas - The array of metadata objects

dev - The device name being sought after

Returns:

The metadata object for the device name or null if it could not be found

Throws:

org.json.JSONException - On any JSON error encountered

getLineups

public Lineup[] getLineups()
                    throws IOException

Description copied from class: EpgClient

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.

Specified by:

getLineups in class EpgClient

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

purgeCache

public void purgeCache()

Description copied from class: EpgClient

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

Specified by:

purgeCache in class EpgClient

purgeCache

public void purgeCache(Object obj)

Description copied from class: EpgClient

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.

Specified by:

purgeCache in class EpgClient

Parameters:

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

deleteMessage

public void deleteMessage(Message msg)
                   throws IOException

Description copied from class: EpgClient

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

Optional operation

Specified by:

deleteMessage in class EpgClient

Parameters:

msg - The message object to be deleted

Throws:

IOException - In case of any IO error upstream

findScheduleGap

public Airing[] findScheduleGap()
                         throws IOException

Check all downloaded schedules for gaps in the airing schedules

The data received from upstream should never have gaps in the schedules. If so, that is an error that invalidates the data in the local cache and the data should no longer be trusted.

Returns:

Null if no gaps are found in any schedules in the local cache or a two element array of Airing objects representing the first gap found

Throws:

IOException - in case of any IO error during the operation

getSystemStatus

public SystemStatus getSystemStatus()
                             throws IOException

Description copied from class: EpgClient

Return details of the current state of the Schedules Direct system

Specified by:

getSystemStatus in class EpgClient

Returns:

The current SD system status

Throws:

IOException - In case of any errors obtaining the status info

fetchLogoStream

protected InputStream fetchLogoStream(Station station)
                               throws IOException

Description copied from class: EpgClient

Fetch a Station's logo object

Specified by:

fetchLogoStream in class EpgClient

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

registerLineup

public int registerLineup(String path)
                   throws IOException

Description copied from class: EpgClient

Register the given lineup with the user's SD account

Optional operation

Specified by:

registerLineup in class EpgClient

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

unregisterLineup

public int unregisterLineup(Lineup l)
                     throws IOException

Description copied from class: EpgClient

Unregister the lineup from the user's SD account

Optional operation

Specified by:

unregisterLineup in class EpgClient

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

searchForLineups

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

Description copied from class: EpgClient

Provide all available lineups for the given location.

Specified by:

searchForLineups in class EpgClient

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

getLineupByUriPath

public Lineup getLineupByUriPath(String path)
                          throws IOException

Description copied from class: EpgClient

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.

Specified by:

getLineupByUriPath in class EpgClient

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

fetchChannelMapping

protected String fetchChannelMapping(Lineup lineup)
                              throws IOException

Description copied from class: EpgClient

Fetch the channel mapping for the given Linup object

Specified by:

fetchChannelMapping in class EpgClient

Parameters:

lineup - The lineup to fetch channel mappings for

Returns:

The JSON encoded response received from upstream

Throws:

IOException - On any IO error