public class NetworkEpgClient extends EpgClient
Use this implementation of EpgClient when you need to download the latest available data directly from the Schedules Direct servers. Use of this client type will always hit the Schedules Direct servers for all requests.
In almost all conceivable real world application scenarions, the NetworkEpgClient should only be used to perform management functions (i.e. check SD server status, check user account status, change user password, submit metadata updates, etc.) It is rare that an application would ever use the NetworkEpgClient instance to directly access EPG data. Instead, applications should always generate and maintain a local cache of their EPG data by downloading it via the sdjson grabber application. The grabber is extremely efficient at maintaining a local cache of a user's EPG data and only requesting data that has changed and needs to be updated in the local cache. Applicatons should periodically call the grabber to update their local cache then use ZipEpgClient instances to access the EPG data in their Java applications.
The NetworkEpgClient class is capable of accessing all of the EPG objects, but it does so one
object at a time and sends a single network request to the Schedules Direct servers for every
such object fetch. Besides being inefficient, this method is extremely slow. Such access to
the EPG data objects is provided for use by the sdjson grabber application and for development,
debugging, and testing of the sdjson package. Most applications should not directly access
their EPG data via this class. Instead, use the grabber app to create a .epg file
then feed that file into an instance of ZipEpgClient to access your EPG data from the cache file,
which is orders of magnitude faster than using this class.
NOTE: Program objects fetched with a NetworkEpgClient will never contain metadata. Metadata is only made available when accessed via a ZipEpgClient with a zip file source that contains the metadata.
API_VERSION| Constructor and Description |
|---|
NetworkEpgClient(String id,
String pwd)
Constructor
|
NetworkEpgClient(String id,
String pwd,
IJsonRequestFactory factory)
ctor; typically only used for development & testing; allows overriding of JsonRequestFactory instance
|
NetworkEpgClient(String id,
String pwd,
String userAgent)
Constructor
|
NetworkEpgClient(String id,
String pwd,
String userAgent,
IJsonRequestFactory factory)
ctor; typically only used for development & testing; allows overriding of JsonRequestFactory instance
|
NetworkEpgClient(String id,
String pwd,
String userAgent,
String baseUrl,
boolean useCache)
Constructor
|
NetworkEpgClient(String id,
String pwd,
String userAgent,
String baseUrl,
boolean useCache,
IJsonRequestFactory factory)
Constructor
|
| Modifier and Type | Method and Description |
|---|---|
protected void |
authorize()
Perform user authorization with Schedules Direct
|
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() |
String |
getHash() |
String |
getId() |
IJsonRequestFactory |
getJsonRequestFactory()
Get the JsonRequestFactory implementation being used by this client
|
Lineup |
getLineupByUriPath(String path)
Get the lineup for the given uri
|
Lineup[] |
getLineups()
Provide all available lineups for the logged in user.
|
String |
getPassword() |
SystemStatus |
getSystemStatus()
Return details of the current state of the Schedules Direct system
|
UserStatus |
getUserStatus()
Get the UserStatus object associated with this EpgClient connection
|
protected void |
initStatusObjects()
Grab the status objects for the user and system from Schedules Direct
|
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
|
protected Lineup[] |
searchForLineups(String location,
String zip)
Provide all available lineups for the given location.
|
InputStream |
submitRequest(JsonRequest req,
Object data)
Submit a self constructed JsonRequest
|
int |
unregisterLineup(Lineup l)
Unregister the lineup from the user's SD account
|
getBaseUrl, getLineups, getUriPathForLineupId, getUserAgent, setBaseUri, setUserAgent, writeLogoToFilepublic NetworkEpgClient(String id, String pwd) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - The Schedules Direct username to authorize withpwd - The Schedules Direct password to authorize withInvalidCredentialsException - Thrown if the given credentials were invalidIOException - Thrown if there is any IO error communicating with the Schedules Direct serversServiceOfflineExceptionpublic NetworkEpgClient(String id, String pwd, IJsonRequestFactory factory) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - pwd - factory - InvalidCredentialsExceptionIOExceptionServiceOfflineExceptionpublic NetworkEpgClient(String id, String pwd, String userAgent) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - The Schedules Direct username to authorize withpwd - The Schedules Direct password to authorize withuserAgent - The user agent to send on all requests to the SD serversInvalidCredentialsException - Thrown if the given credentials were invalidIOException - Thrown if there is any IO error communicating with the Schedules Direct serversServiceOfflineException - Thrown if the web service reports itself as offline/unavailablepublic NetworkEpgClient(String id, String pwd, String userAgent, IJsonRequestFactory factory) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - pwd - userAgent - factory - InvalidCredentialsExceptionIOExceptionServiceOfflineExceptionpublic NetworkEpgClient(String id, String pwd, String userAgent, String baseUrl, boolean useCache) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - The Schedules Direct username to authorize withpwd - The Schedules Direct password to authorize withuserAgent - The user agent to send on all requests to the SD serversbaseUrl - The base URL to use for all HTTP communication; most should not set this value as it is for testing and development only!useCache - Should the client instance maintain a cache of created objects or hit the SD server on every request? Though memory intensive, use of the cache is greatly encouraged!factory - The JsonRequestFactory to be used for this client to generate network requestsInvalidCredentialsException - Thrown if the given credentials were invalidIOException - Thrown if there is any IO error communicating with the Schedules Direct serversServiceOfflineException - Thrown if the web service reports itself as offline/unavailablepublic NetworkEpgClient(String id, String pwd, String userAgent, String baseUrl, boolean useCache, IJsonRequestFactory factory) throws InvalidCredentialsException, IOException, ServiceOfflineException
id - The Schedules Direct username to authorize withpwd - The Schedules Direct password to authorize withuserAgent - The user agent to send on all requests to the SD serversbaseUrl - The base URL to use for all HTTP communication; most should not set this value as it is for testing and development only!useCache - Should the client instance maintain a cache of created objects or hit the SD server on every request? Though memory intensive, use of the cache is greatly encouraged!factory - The JsonRequestFactory to be used for this client to generate network requestsInvalidCredentialsException - Thrown if the given credentials were invalidIOException - Thrown if there is any IO error communicating with the Schedules Direct serversServiceOfflineException - Thrown if the web service reports itself as offline/unavailablepublic IJsonRequestFactory getJsonRequestFactory()
protected void authorize()
throws InvalidJsonObjectException,
InvalidCredentialsException,
IOException,
ServiceOfflineException
InvalidCredentialsException - Thrown if authorization failedIOException - Thrown on any IO error communicating with the Schedules Direct serversServiceOfflineException - Thrown if the web service reports itself as offline/unavailableInvalidJsonObjectException - Thrown if the response object is not in the expected formatprotected void initStatusObjects()
throws IOException
IOException - On any IO error, including an error response from the serverpublic UserStatus getUserStatus() throws IOException
EpgClientgetUserStatus in class EpgClientIOException - Thrown if there is any kind of IO error accessing the raw data feedpublic Lineup[] getLineups() throws IOException
EpgClientThis 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.
getLineups in class EpgClientIOException - Thrown if there is any kind of IO error accessing the data feedprotected Lineup[] searchForLineups(String location, String zip) throws IOException
EpgClientsearchForLineups in class EpgClientlocation - 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 forIOException - Thrown if there is any kind of IO error accessing the raw data feedpublic String getId()
public String getPassword()
public String getHash()
public void close()
throws IOException
EpgClientclose in class EpgClientIOException - On any IO errorprotected void finalize()
throws Throwable
public InputStream submitRequest(JsonRequest req, Object data) throws IOException
Meant for development only, but can also be used to handle parts of the Schedules Direct service not directly implemented by this API (yet).
This method will replace the UserAgent and hash properties of the JsonRequest argument with those of this client.
If there are production needs to use this method by people, then please open a ticket at the project site to get the missing API features implemented into a future release.
req - A JsonRequest to be submitted to the servicedata - The data to attach to the request or null if no data is to be attachedIOException - On any errorprotected Airing[] fetchSchedule(Station station) throws IOException
EpgClientfetchSchedule in class EpgClientstation - The station to fetch the airing schedule forIOException - Thrown on any IO error accessing the schedule dataprotected Program fetchProgram(String progId) throws IOException
EpgClientfetchProgram in class EpgClientprogId - The program id to fetchIOException - Thrown on any IO error accessing the dataprotected Map<Station,Airing[]> fetchSchedules(Lineup lineup) throws IOException
EpgClientThis method is preferred to fetchSchedule() as it will grab multiple schedules much more efficiently. Use this when ever you can.
fetchSchedules in class EpgClientlineup - The Lineup object to download schedules forIOException - In case of any IO error accessing the dataprotected Map<String,Program> fetchPrograms(String[] progIds) throws IOException
EpgClientThis method is preferred to fetchProgram() as it will grab multiple programs much more efficiently. Use this when ever you can.
fetchPrograms in class EpgClientprogIds - An array of program ids to fetchIOException - On any IO error accessing the datapublic void purgeCache()
EpgClientpurgeCache in class EpgClientpublic void purgeCache(Object obj)
EpgClientpurgeCache in class EpgClientobj - The object to purge from the client's local cachepublic void deleteMessage(Message msg) throws IOException
EpgClientOptional operation
deleteMessage in class EpgClientmsg - The message object to be deletedIOException - In case of any IO error upstreampublic SystemStatus getSystemStatus() throws IOException
EpgClientgetSystemStatus in class EpgClientIOException - In case of any errors obtaining the status infoprotected InputStream fetchLogoStream(Station station) throws IOException
EpgClientfetchLogoStream in class EpgClientstation - The station whose logo is to be fetchedIOException - Thrown on any IO errorpublic int registerLineup(String path) throws IOException
EpgClientOptional operation
registerLineup in class EpgClientpath - The full, absolute URI of the lineup to register; perhaps grab this value from EpgClient.getUriPathForLineupId()IOException - On any IO errorpublic int unregisterLineup(Lineup l) throws IOException
EpgClientOptional operation
unregisterLineup in class EpgClientl - The linup to unregister from the user's accountIOException - On any IO errorprotected String fetchChannelMapping(Lineup lineup) throws IOException
EpgClientfetchChannelMapping in class EpgClientlineup - The lineup to fetch channel mappings forIOException - On any IO errorpublic Lineup getLineupByUriPath(String path) throws IOException
EpgClientNOTE: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.
getLineupByUriPath in class EpgClientpath - The absolute path to access the lineup data from; appended to BASE_URL to form full URI to be accessedIOException - Thrown if there is any kind of IO error accessing the raw data feedCopyright © 2012–2014 Battams, Derek. All rights reserved.