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