OpenCable™ UPnP Facade Design DRAFT Notice This document is an effort for the benefit of the OpenCable Team. Neither CableLabs, nor any other entity participating in the creation of this document, is responsible for any liability of any nature whatsoever resulting from or arising out of use or reliance upon this document by any party. This document is furnished on an AS-IS basis and neither CableLabs, nor other participating entity, provides any representation or warranty, express or implied, regarding its accuracy, completeness, or fitness for a particular purpose. Distribution of this document is restricted to internal CableLabs personnel. Copyright 2008 Cable Television Laboratories, Inc. All rights reserved. OpenCable™ - Content Database Design Version History Version Number V 0.5 Date 1/2/2009 Contributor Michael A. Jastad CableLabs Description Initial draft ii OpenCable™ - Content Database Design Table of Contents CableLabs iii OpenCable™ - Content Database Design Figures Tables Table 1 - Document Text Conventions ....................................................................... Error! Bookmark not defined. CableLabs iv OpenCable™ - UPnP Facade Design 1 INTRODUCTION The UPnP Façade provides UPnP discovery and control semantics, while isolating the OCAP HN extension implementation from third party UPnP libraries and implementations, and abstracts the various UPnP networking protocols. The Facade also provides transparency to integrators, and adopters of the OCAP RI to use “off the shelf”, pluggable UPnP offerings without having to change existing OCAP HN Ext implementations. 2 FUNCTIONAL DESCRIPTION The UPnP Façade is partitioned into 2 distinct functional libraries, a Client Facade supporting device discovery, event registration, and service action/control invocation, and Server Facade providing UPnP server side support for UPnP devices (i.e. Digital Media Servers, Digital Media Players, etc…), and services (i.e. Content Directory, Scheduled Recording, etc…). 2.1 Client Facade The Client Façade provides a set of concrete API’s for discovering devices and services participating in a UPnP managed network. The Client Façade also provides methods for service control invocation, and event registration and notification of managed UPnP devices and services. 2.2 Server Facade The Server Façade deploys an HTTP Server to listen for HTTP requests from UPnP Clients, dispatch the requests to registered UPnP services, and forward a response to the client making the request. The Server side also provides event announcements when devices enter and exit from the UPnP network, or when a Service has performed updates to managed content. CableLabs 1 OpenCable™ - Content Database Design 3 HIGH LEVEL DESCRIPTION The following is a high level illustration of both the Client and Server Façade API, and the relationships between the interfaces. 1. Client Facade UPnP Facade Client Facade IControl Point IDevice IService IAction IArgument Component Client Side Facade Context Description UPnPFacade Factory IClientFacade IControlPoint Singleton Singleton IDevice IService IAction Public Public Public IArgument Public CableLabs Generates the singleton instances for the Client and Server side façade components Provides A UPnP control point (client). This object is transparent to consumers of the Client Façade. It performs the discovery, and control on behalf of the Client Façade. Represents the discovered device. Represents the services for a given device. Represents the control actions for a given service. An overloaded object representing: - Input method parameters - Output/Return values encapsulated in a response. 2 OpenCable™ - Content Database Design 2. Server Facade UPnP Facade IListener Server Facade IEvent IServer IRequest Component Server Side Facade Context Description UPnPFacade Library IServerFacade API/Façade IServer Static IListener Public IEvent Public IRequest Public IArgument Public CableLabs IArgument A 3rd party UPnP compliant java library providing UPnP Discovery, Description, Control, and Eventing. An implementation of the Façade Design Pattern used to provide loose coupling of OCAP HN implementation and the UPnP SW stack. The Server Façade provides HTTP Server function. Acts as a UPnP Media Server device. Provides announce, description, and Service control. Advertises IP, Port, and protocol (HTTP). Listens for http requests, and facilitates http responses. Event Listener used as a callback mechanism. Event object returned as part of the notification Contains information about the type of request. The IRequest object is generated by the IServer when it receives an HTTP request. The IServer uses the Event Listener mechanism to notify registered observers, which includes the IRequest object. An overloaded object representing: - Input method parameters - Output/Return values encapsulated in a response. 3 OpenCable™ - Content Database Design 3.1.2 Assumptions The design evolved around the concept that various UPnP software components could be used and that the OCAP stack was to perform as expected with little or no variance in function or features. 3.1.3 Design Goals The goal of the design is to expose an object oriented API exhibiting UPnP constructs and semantics. The design will abstract and isolate UPnP vendor software allowing implementers to use various UPnP libraries. 3.1.4 Component Interaction Diagram 3.1.4.1.1 Client Side The following is a component interaction diagram of the Client Side framework and the OCAP HN Implementation integration. Client Side A P P O C A P A P I Discovery IDevice OCAP HN Impl IClientFacade IService IAction Description U P n P Control Eventing IArgument DATA/CONTROL FLOW Client-Side components are designed to provide UPnP Device and Service support for OCAP HN. The following table outlines the Client-Side components, their context (lifecycle), and a description of their role within the Client-Side framework. Component Client Side Framework Context Description UPnP Library IClientFacade API/Façade IDevice IService API/Façade API/Façade IAction API/Facade CableLabs A 3rd party UPnP compliant java library providing UPnP Discovery, Description, Control, and Eventing. An implementation of the Façade Design Pattern used to provide loose coupling of OCAP HN implementation and the UPnP SW stack. Represents a discovered upnp device Represents a discovered upnp service for a given upnp device Represents a control action supported by a upnp service 4 OpenCable™ - Content Database Design 3.1.4.1.2 Server Side The following is a component interaction diagram of the Server Side framework and the Content Directory Service. Server Side OCAP HN Ext Impl CDS IMedia Server Content Database IServerFacade SRS U P n P HTTP Request HTTPResponse Eventing DATA/CONTROL FLOW Server-Side components are designed to provide UPnP Device and Service support for OCAP HN. The following table outlines the Server-Side components, their context (lifecycle), and a description of their role within the Server-Side framework. 3.1.5 Component Server Side Framework Context Description UPnP Library IServerFacade API/Façade IMediaServer Static A 3rd party UPnP compliant java library providing UPnP Discovery, Description, Control, and Eventing. An implementation of the Façade Design Pattern used to provide loose coupling of OCAP HN implementation and the UPnP SW stack. The Server Façade provides HTTP Server function. Acts as a UPnP Media Server device. Provides announce, description, and Service control. Advertises IP, Port, and protocol (HTTP). Listens for http requests, and facilitates http responses. Non Functional Requirements There are no Non Functional requirements at this time. 3.1.6 Design Rationale The Façade API design is based on transforming UPnP managed entities (control point, devices, services, etc…), and organizing them so that they have meaningful relationships between the entities. CableLabs 5 OpenCable™ - Content Database Design 3.1.7 Components Affected Component NetManager MetModule Integration Point OCAP HN Ext API Impl OCAP HN Ext API Impl Description 4 FUNCTIONAL COMPONENTS 4.1 Façade 4.1.1 Class UPnPFacade public class UPnPFacade UPnPFacade is a UPnP Facade singleton class factory that returns a singleton instance of IClientFacade or IServerFacade. Constructor Summary UPnPFacade() Method Summary static IClientFacade getClientFacade() Returns a singleton handle to the IClientFacade instance static IServerFacade getServerFacade() Returns a singleton handle to the IServerFacade instance 4.1.2 Package org.cablelabs.ocap.hn.upnp.facade Interface Summary IAction IAction is an interface representing a UPnP Control Action for a specified UPnP Service. IActionRequestReceivedEvent IActionRequestReceivedEvent is generated when an HTTP request has been generated and caught by IServer. IActionRequestReceivedListener IRequestReceivedListener interface is a Server-side call-back registered by UPnP Services monitoring for incoming action requests. CableLabs 6 OpenCable™ - Content Database Design IActionResponseReceivedEvent IActionResponseReceivedEvent is generated when an HTTP response has been generated and caught by Client-side services. IActionResponseRevceived Listener is an interface that defines the behavior IActionResponseReceivedListener of a Client-side Observer registering for a call-back for the completion of a UPnP Service Control Action. IArgument IArgument - provides access to pairs for a specific argument that is passed in as part of an UPnP Action Request, or generated and returned as part of a UPnP Action Response. IClientFacade IClientFacade is a UPnP client interface for discovering devices and services within a UPnP network, monitoring for events, and facilitating Service Control Actions. IControlPoint IControlPoint acts as a UPnP Control Point. IDevice IDevice is an interface for retrieving properties, attributes, and state as well as registering Listeners of a UPnP managed Device. IEvent IEvent is a base Event object and is generated and caught by Client-side services. IEventListener IEventListener is an interface used as a call-back by an Observer interested in State changes of a given Object allowing registration of IEventListeners. IListener IListener is an interface that defines the basic behavior of an Observer registering for a call-back of "state changes" of a specified object. IRequest IRequest represents an HTTP request and is generated for Server-side registered services. IResponse IResponse represents the result from a Service Action request. IServer The IServer runs as an HTTP Server on behalf of a UPnP Device and it's associated services. IServerFacade Provides UPnP Server side support for Devices and Services. IService IService is an interface providing access to UPnP Service properties, and is used in conjunction with IClientFacade. IServiceStateTable IServiceStateTable provides APIs for supported UPnP Service states. ISubscriptionListener Class Summary UPnPFacade 4.1.3 UPnPFacade is a UPnP Facade singleton class factory that returns a singleton instance of IClientFacade or IServerFacade. Interface IClientFacade public interface IClientFacade IClientFacade is a UPnP client interface for discovering devices and services within a UPnP network, monitoring for events, and facilitating Service Control Actions. IClientFacade manages CableLabs 7 OpenCable™ - Content Database Design it's own UPnP Control Point, and bridges UPnP client functions between a concrete implementation, and a third party UPnP library. Method Summary void addControlPointEventListener(IEventListener l) Adds an EventListener on behalf of an Observer who is interested in receiving events related to UPnP ControlPoint state changes. void addDeviceEventListener(IEventListener l) Adds an EventListener on behalf of an Observer who is interested in receiving events related to UPnP Device state changes. void discover(IEventListener eventListener) void doAction(IAction a, IActionResponseReceivedListener l) Performs a UPnP Control Action on a service. IAction[] getActions(IService dev) Retrieves a list of supported Actions for a specified IService from the Facade Control Point and maps them to consumable Action objects for concrete implementations. IDevice[] getDevices() Retrieves a list of discovered UPnP devices from the Facade Control Point and maps them to consumable Device objects for concrete implementations. IDevice[] getDevices(IDevice dev) Retrieves a list of discovered UPnP embedded devices from the Facade Control Point, given a specified IDevice and maps them to consumable Device objects for concrete implementations. IService[] getServices(IDevice dev) Retrieves a list of discovered UPnP Services for a specified IDevice from the Facade Control Point and maps them to consumable Service objects for concrete implementations. void removeControlPointEventListener(IEventListener l) Removes an EventListener on behalf of an Observer who is no longer interested in receiving events related to UPnP ControlPoint state changes. void removeDeviceEventListener(IEventListener l) Removes an EventListener on behalf of an Observer who is no longer interested in receiving events related to UPnP Device state changes. 4.1.4 Interface IControlPoint public interface IControlPoint IControlPoint acts as a UPnP Control Point. It performs device and service discovery, event monitoring and service control within a UPnP network. Method Summary CableLabs 8 OpenCable™ - Content Database Design void addEventListener(IEventListener fel) Adds an EventListener on behalf of an Observer who is interested in receiving events related to UPnP ControlPoint state changes. void eventNotify() Used by the Control Point to notify registered observers of state changes. int getState() Used by consumers to synchronously retrieve current state of the control point. void removeEventListener(IEventListener fel) Removes an EventListener on behalf of an Observer who is no longer interested in receiving events related to UPnP ControlPoint state changes. void setState(int state) Used by the Control Point to set the Event State for Observer call-back. void startDiscover() Starts Control Point Discovery process. void stopDiscover() Stops the Control Point Discovery process. 4.1.5 Interface IDevice public interface IDevice IDevice is an interface for retrieving properties, attributes, and state as well as registering Listeners of a UPnP managed Device. Method Summary int getDeviceType() Retrieves the Device's Model type java.lang.String getManufacturer() Retrieves the Device's Manufacturer java.lang.String getModel() Retrieves the Device's Model name java.lang.String getName() Retrieves the Device's human readable name. java.lang.String getSerialNumber() Retrieves the Device's Serial Number java.lang.String getUID() Retrieves the Device's Unique Identifier. java.lang.String getURL() Retrieves the Device's Universal Record Locater CableLabs 9 OpenCable™ - Content Database Design void setName(java.lang.String name) Sets the Device's human readable name. void setUID(java.lang.String uid) Sets the Device's Unique Identifier used during device discovery. 4.1.6 Interface IService public interface IService IService is an interface providing access to UPnP Service properties, and is used in conjunction with IClientFacade. Method Summary java.lang.String geServiceID() Returns the unique service ID for this service. java.lang.String getControlURL() Returns the Control URL for this service IDevice getDevice() Returns the parent device owning this service. java.lang.String getServiceID() Returns the Service ID for this service. IServiceStateTable getServiceState() REturns the state table for this service. int getServiceType() Returns the Service Type boolean isService(java.lang.String name) Determines if this service is of type name 4.1.7 Interface IAction public interface IAction IAction is an interface representing a UPnP Control Action for a specified UPnP Service. This interface is used in conjunction with IClientFacade. Field Summary static int CDS_BROWSE_ACTION CableLabs 10 OpenCable™ - Content Database Design static int CDS_CREATE_ACTION static int CDS_GETSEARCHCAPABILITIES_ACTION static int CDS_MODIFY_ACTION static int CDS_SEARCH_ACTION static int SRS_SCHEDULERECORDING_ACTION Method Summary int getActionType() Returns the type of Action IArgument[] getRequestArguments() Retrieve the Input Arguments IService getService() Retrieve the Service this action belongs to. void setRequestArguments(IArgument[] args) Sets the request Arguments for this action void setRequestArgumentValue(java.lang.String name, int value) Sets a specified String value Argument void setRequestArgumentValue(java.lang.String name, java.lang.String value) Sets a specified String value Argument 4.1.8 Interface IArgument public interface IArgument IArgument - provides access to pairs for a specific argument that is passed in as part of an UPnP Action Request, or generated and returned as part of a UPnP Action Response. Method Summary IAction getAction() Returns the parent IAction associated with this argument. java.lang.String getArgumentKey() Returns the Argument key identifying this argument. java.lang.String getArgumentValue() Returns the Argument value representing this argument. CableLabs 11 OpenCable™ - Content Database Design IService getService() Returns the Service associated with this Argument 4.1.9 Interface IServerFacade public interface IServerFacade Provides UPnP Server side support for Devices and Services. Implements an HTTP Server on behalf of a device. The HTTP Server binds and listens on a configured port for HTTP requests, and notifies registered services as requests are received. Method Summary void addRequestReceivedListner(IActionRequestReceivedListener requestReceiv edListener) Adds a listener on behalf of a UPnP Service that will receive and respond to Control Action requests. void addSubscriptionListener(ISubscriptionListener subListener) Adds a call-back mechanism for services. void announce(java.io.File description) provides a mechanism for Devices and services to announce themselves along with their associated properties via a Description file. IServ getServerInstance() er Returns a handle to the IServer void initServer() Initializes the IServer singleton. void responseSend(IResponse response, IAction action) Sends an Action Response to a UPnP Action request 4.1.10 Interface IServer public interface IServer The IServer runs as an HTTP Server on behalf of a UPnP Device and it's associated services. The IServer configures itself to a specified IP:Port address and listens for HTTP requests and posts responses. Requests are received and dispatched to registered Services for processing. When a registered service receives the request, it performs the request and posts the appropriate response using the IServer API. CableLabs 12 OpenCable™ - Content Database Design Field Summary static int TYPE_MEDIA_PLAYER_SERVER Media Player Type static int TYPE_MEDIA_RECORDER_SERVER Media Recorder Type static int TYPE_MEDIA_SERVER Media Server Type Method Summary void addRequestReceivedListner(IActionRequestReceivedListener reques tReceivedListener) Adds a listener on behalf of a UPnP Service that will receive and respond to Control Action requests. void announce(java.io.File description) provides a mechanism for Devices and services to announce themselves along with their associated properties via a Description file. java.lang.St getModel() ring Return the model information for this server java.lang.St getPort() ring Returns the port for this Server int getServerType() Return the type of the IServer java.lang.St getURL() ring Returns the Universal Record Locator for this Server java.lang.St getVendor() ring Return the vendor information for this server boolean isRunning() Returns true if the server is running, false otherwise void start() Starts the Server. void stop() Stops the Server CableLabs 13 OpenCable™ - Content Database Design 4.1.11 Interface IActionRequestReceivedEvent IActionRequestReceivedEvent is generated when an HTTP request has been generated and caught by IServer. Registered Services implementing the IActionRequestReceviedListener will process this Event. Field Summary static int ACTION_COMPLETE_EVENT An Event Type indicating that a upnp control action on a service has completed static int DEVICE_ALIVE_EVENT An Event Type indicating that a device is alive static int DEVICE_ANNOUNCE_EVENT An Event Type indicating a device has joined the upnp network or is re-announcing itself static int DEVICE_BYEBYE_EVENT An Event Type indicating a device has left or is leaving the upnp network static int DEVICE_DISCOVER_EVENT An Event Type indicating that a devices has been discovered during a search static int DEVICE_NOTIFY_EVENT An Event Type indicating that a Device is notifying the upnp network of a state change static int DEVICE_SEARCH_RESPONSE_EVENT An Event Type indicating that a Control Point state has changed in response to a search Method Summary IRequest getRequest() Retrieves the response from a previous request action Methods inherited from interface org.cablelabs.ocap.hn.upnp.facade.IEvent getEvent 4.1.12 Interface IActionRequestReceivedListener IRequestReceivedListener interface is a Server-side call-back registered by UPnP Services monitoring for incoming action requests. The Event associated with this listener is in the form of an IActionRequestReceivedEvent Method Summary void notifyEvent(IActionRequestReceivedEvent e) The method used to notify a Server side Observer owning the listener that an HTTP request Event has occurred. CableLabs 14 OpenCable™ - Content Database Design 4.1.13 Interface IActionResponseReceivedEvent IActionResponseReceivedEvent is generated when an HTTP response has been generated and caught by Client-side services. Registered consumers implementing the IActionResponseReceviedListener will process this Event. Field Summary Fields inherited from interface org.cablelabs.ocap.hn.upnp.facade.IEvent ACTION_COMPLETE_EVENT, DEVICE_ALIVE_EVENT, DEVICE_ANNOUNCE_EVENT, DEVICE_BYEBYE_EVENT, DEVICE_DISCOVER_EVENT, DEVICE_NOTIFY_EVENT, DEVICE_SEARCH_RESPONSE_EVENT Method Summary IResponse getResponse() Retrieves the response from a previous request action 4.1.14 Interface IActionResponseReceivedListener IActionResponseRevceived Listener is an interface that defines the behavior of a Client-side Observer registering for a call-back for the completion of a UPnP Service Control Action. The Event associated with this listener is in the form of an IActionResonseReceivedEvent Method Summary void notifyEvent(IActionResponseReceivedEvent e) The method used to notify a Client side Observer owning the listener that an HTTP response Event has occurred from a previous request. CableLabs 15 OpenCable™ - Content Database Design 5 BUILD/PACKAGING 5.1 Package org.cablelabs.ocap.hn.upnp.facade The java package containing the Façade Interfaces. 5.2 Package org.cablelabs.impl.ocap.hn.upnp.facade The java package containing the Façade implementation. CableLabs 16 OpenCable™ - Content Database Design 6 ANNEX A 6.1 Exceptions Exceptions Exception Description CableLabs 17