Commit a0e2bd88 authored by agordon's avatar agordon

initial import of opencable CANH APIs

parent 71701989
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAAuthorization.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.rmi.Remote;
import java.rmi.RemoteException;
/**
* Calls to the <code>CAHandler</code>'s <code>getSourceAuthorization</code>, <code>getResourceAuthorization</code> and
* <code>getIppvAuthorization</code> methods return objects that implement this interface.
* In addition to providing authorization status for a specific point in time,
* <code>CAAuthorization</code>s can monitor for changes in authorization state. The choice of
* static versus monitoring is determined by the presence of a <code>CAAuthorizationListener</code>
* in the call to the <code>CAHandler</code>'s get authorization method that returns the
* <code>CAAuthorization</code>. When a <code>CAAuthorization</code> instance is monitoring, the CANH Server Xlet
* SHALL reflect any authorization changes in the <code>CAAuthorization</code>'s state before an event
* is delivered to the listener. Thus, upon receiving an event, the listener can determine
* the new authorization state through calls to <code>CAAuthorization</code> methods such as
* <code>isAuthorized()</code>.
*/
public interface CAAuthorization extends Remote
{
/**
* Indicates an authorization for a source. Used as the target type for <code>CAAuthorization</code>s
* that are obtained with the <code>CAHandler.getSourceAuthorization</code> method.
*/
public static final int SOURCE_TARGET = 1;
/**
* Indicates an authorization for an entitlement. Used as the target type for <code>CAAuthorizations</code>
* that are obtained with the <code>CAHandler.getResourceAuthorization</code> method.
*/
public static final int RESOURCE_TARGET = 2;
/**
* Indicates an authorization for a PPV event. Used as the target type for <code>CAAuthorizations</code>
* that are obtained with the <code>CAHandler.getIppvAuthorization</code> method.
*/
public static final int PPV_TARGET = 3;
/**
* Returns an indication of the type of object checked.
*
* @return one of <code>SOURCE_TARGET</code>, <code>RESOURCE_TARGET</code> or <code>PPV_TARGET</code>.
* <ul>
* <li> Set to <code>SOURCE_TARGET</code> for <code>CAAuthorization</code>s returned by <code>CAHandler.getSourceAuthorization()</code>.
* <li> Set to <code>RESOURCE_TARGET</code> for <code>CAAuthorization</code>s returned by <code>CAHandler.getResourceAuthorization()</code>.
* <li> Set to <code>PPV_TARGET</code> for <code>CAAuthorization</code>s returned by <code>CAHandler.getIppvAuthorization()</code>.
* </ul>
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public int getTargetType()
throws RemoteException;
/**
* Returns the ID of the authorization's target. For a <code>CAAuthorization</code> with
* a target type of <code>SOURCE_TARGET</code> the source ID is returned. For <code>RESOURCE_TARGET</code>
* the entitlement ID is returned. For <code>PPV_TARGET</code> the PPV event entitlement ID
* is returned.
*
* @return the ID of the authorization's target.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public long getTargetId()
throws RemoteException;
/**
* Returns true if the queried object is authorized, for any reason. If the
* object target type is <code>PPV_TARGET</code>, and the current purchase state is
* <code>IPPV_PURCHASE_PENDING</code>, this method SHALL return the actual authorization
* state of the queried object. The encrypted state SHALL NOT affect the
* authorization state of the queried object. If the target type is <code>PPV_TARGET</code>
* the free preview state SHALL NOT affect the authorization state of the
* queried object.
*
* @return True if object is authorized, false if the object is not authorized.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public boolean isAuthorized()
throws RemoteException;
/**
* Determines if this <code>CAAuthorization</code> is currently in the free preview period for a PPV event.
* Relevant only for <code>CAAuthorization</code>s with a target type of <code>PPV_TARGET</code> or
* <code>SOURCE_TARGET</code>. Returns true if this <code>CAAuthorization</code> is in the free preview period. Returns
* false if this <code>CAAuthorization</code> is not in the free preview period.
*
* @return true if this <code>CAAuthorization</code> is in the free preview period for the PPV event. false if
* this <code>CAAuthorization</code> is not in the free preview period.
*
* @throws IllegalStateException Thrown if the target type is not <code>PPV_TARGET</code>
* or <code>SOURCE_TARGET</code>.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public boolean isFreePreviewable()
throws IllegalStateException, RemoteException;
/**
* Determines if this <code>CAAuthorization</code> is authorized because of a subscription
* purchase.
*
* @return True if a subscription was purchased for the queried object.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public boolean isSubscriptionPurchased()
throws IllegalStateException, RemoteException;
/**
* Determines if this <code>CAAuthorization</code> is authorized because of a PPV event
* purchase. Can be used with <code>CAAuthorization</code>s with a target type of either
* <code>PPV_TARGET</code> or <code>SOURCE_TARGET</code>. If a purchase is in the <code>IPPV_PURCHASE_PENDING</code>
* state this method SHALL return false.
*
* @return True if an IPPV event purchased for the queried object.
* @throws IllegalStateException Thrown if the target type is not <code>PPV_TARGET</code>
* or <code>SOURCE_TARGET</code>.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public boolean isIppvEventPurchased()
throws IllegalStateException, RemoteException;
/**
* Determines if the <code>CAAuthorization</code> is being monitored for authorization changes and
* being updated when the authorization state changes in the future. Returns true for
* <code>CAAuthorization</code>s that are obtained by calling the <code>CAHandler</code>'s <code>getSourceAuthorization</code>,
* <code>getResourceAuthorization</code> or <code>getIppvAuthorization</code> methods with a listener.
* Returns false after the <code>stopMonitoring</code> method is called.
*
* @return True if the this <code>CAAuthorization</code> is monitoring for authorization changes
* else returns false.
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public boolean isMonitoring()
throws RemoteException;
/**
* Causes this <code>CAAuthorization</code> to stop monitoring for authorization changes, and stop
* sending <code>CAAuthorizationEvent</code>s to the <code>CAAuthorizationListener</code> that was
* registered with this <code>CAAuthorization</code>. Does nothing if <code>isMonitoring()</code> is already false.
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public void stopMonitoring()
throws RemoteException;
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAAuthorizationEvent.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.rmi.RemoteException;
import java.util.EventObject;
import com.opencable.handler.cahandler.CAAuthorization;
/**
* An authorization-related event associated with a <code>CAAuthorization</code>.
* Note that the <code>EventObject.getSource()</code> method returns null
* once this object has been passed across an IXC interface.
*/
public final class CAAuthorizationEvent extends EventObject
{
// Serialization UID should NOT be changed when fields are added to this class.
static final long serialVersionUID = -5638212430595178404L;
private long m_targetId;
private int m_targetType;
private boolean m_isTargetAuthorized;
/**
* Creates a new instance of a <code>CAAuthorizationEvent</code>.
*
* @param authorization The source of the event
*/
public CAAuthorizationEvent(CAAuthorization authorization)
{
super(authorization);
try
{
m_targetId = authorization.getTargetId();
m_targetType = authorization.getTargetType();
m_isTargetAuthorized = authorization.isAuthorized();
}
catch(RemoteException e)
{
// Should never happen
}
}
/**
* Returns the ID of the item whose authorizations have changed.
*
* @return A source or entitlement ID
*/
public long getTargetId()
{
return m_targetId;
}
/**
* Returns an indication of the type of object whose authorization has changed.
*
* @return One of <code>SOURCE_TARGET</code>, <code>RESOURCE_TARGET</code>, or <code>PPV_TARGET</code>.
*/
public int getTargetType()
{
return m_targetType;
}
/**
* Returns the authorization status of the item whose authorizations have changed.
*
* @return true, if access to the item named by <code>getTargetId()</code> is allowed false otherwise.
*/
public boolean isTargetAuthorized()
{
return m_isTargetAuthorized;
}
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAAuthorizationListener.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.util.EventListener;
import com.opencable.handler.cahandler.CAAuthorizationEvent;
/**
* Defines an object that listens for <code>CAAuthorizationEvents</code>
*/
public interface CAAuthorizationListener extends EventListener, Remote
{
/**
* Invoked to deliver a <code>CAAuthorizationEvent</code>.
*
* @param event The delivered event.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public void deliverEvent(CAAuthorizationEvent event)
throws RemoteException;
}
This diff is collapsed.
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAHandlerStateEvent.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.util.EventObject;
import com.opencable.handler.cahandler.CAHandler;
/**
* A CA Handler State event that reports the change of state of the CA Handler. Note that
* the <code>EventObject.getSource()</code> method returns null when this event object has been passed
* across an IXC interface.
*/
public final class CAHandlerStateEvent extends EventObject
{
// Serialization UID should NOT be changed when fields are added to this class
static final long serialVersionUID = 878928767327114860L;
private int m_newState;
/**
* Creates a new <code>CAHandlerStateEvent</code>
* @param source The <code>CAHandler</code> that was the source of the event.
* @param newState The new state taken from the CAH_* constants defined
* in the <code>CAHandler</code> interface.
*/
public CAHandlerStateEvent(CAHandler source, int newState)
{
super(source);
m_newState = newState;
}
/**
* Returns the new state of the <code>CAHandler</code>, which SHALL be one of the of the the <code>CAH_*</code> constant values defined in the <code>CAHandler</code> interface.
* <br>
* The values are as follows:
* <ul>
* <li> <code>CAH_INITIALIZING</code> the CA handler is in the process of initializing and is not ready to process requests.
* <li> <code>CAH_READY</code> the CA handler is ready to process requests
* <li> <code>CAH_ERROR_START</code> The start of a range of error codes indicating that the CA handler has encountered an error and cannot process requests. The meaning of each error code is implementation specific.
* <li> <code>CAH_ERROR_END</code> The end of a range of error codes indicating that the CA handler has encountered an error and cannot process requests. The meaning of each error code is implementation specific.
* </ul>
*
* @return One of the <code>CAH_*</code> constant values defined in the CAHandler class.
*/
public int getNewState()
{
return m_newState;
}
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAHandlerStateListener.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.util.EventListener;
import com.opencable.handler.cahandler.CAHandlerStateEvent;
/**
* Defines an object that listens for <code>CAHandlerStateEvents</code>.
*/
public interface CAHandlerStateListener extends Remote, EventListener
{
/**
* Invoked to deliver a <code>CAHandlerStateEvent</code>.
*
* @param event The delivered event.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public void deliverEvent(CAHandlerStateEvent event)
throws RemoteException;
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAIOException.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
import java.io.IOException;
/**
* This exception if thrown when the <code>CAHandler</code> is unable to communicate with CAS client.
* This class is used instead of <code>IOException</code> to avoid potential confusion with RemoteExceptions
* that can be throw as a result of IXC communication errors.
*/
public final class CAIOException extends IOException
{
/**
* Creates a <code>CAIOExpection</code> with null as the error detail message.
*/
public CAIOException()
{
}
/**
* Creates a <code>CAIOExpection</code> with the specified detail message that can be retrieved
* with the <code>Throwable.getMessage()</code> method.
*
* @param message The detail message.
*/
public CAIOException(String message)
{
super(message);
}
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: CAInsufficientResources.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.cahandler;
/**
* This exception is used to indicate that the <code>CAHandler</code> does
* not have sufficient resources to perform a requested operation.
*/
public class CANoResourcesException extends Exception
{
/**
* Creates a <code>CANoResourcesException</code> with null as the error detail message.
*/
public CANoResourcesException()
{
super();
}
/**
* Creates a <code>CANoResourcesExpection</code> with the specified detail message that can be retrieved
* with the <code>Throwable.getMessage()</code> method.
*
* @param message The detail message.
*/
public CANoResourcesException(String message)
{
super(message);
}
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: NetHandler.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.nethandler;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.util.Properties;
import com.opencable.handler.nethandler.NetHandlerStateListener;
import com.opencable.handler.nethandler.NetMessageListener;
/**
* Primary point of contact for Network specific functions.
*/
public interface NetHandler extends Remote
{
/**
* The Network handler is in the process of initializing and is not ready to
* process requests.
*/
public static final int NH_INITIALIZING = 0x01;
/** The Network handler is ready to process requests. */
public static final int NH_READY = 0x02;
/**
* The start of a range of error codes indicating that the Network handler has
* encountered an error and cannot process requests. The meaning of each error
* code is implementation specific.
*/
public static final int NH_ERROR_START = 0x100;
/**
* The end of a range of error codes indicating that the Network handler has
* encountered an error and cannot process requests. The meaning of each error
* code is implementation specific.
*/
public static final int NH_ERROR_END = 0x1FF;
/** Name to be used when registering a <code>NetHandler</code> with IXC */
public static final String IXC_NAME = "com.opencable.handler.nethandler.NetHandler";
/**
* Returns the CANH API version that is supported by this <code>NetHandler</code> implementation.
*
* @return the CANH API version that is supported by this <code>NetHandler</code> implementation as
* String. Must be "D01" for this version.
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public String getAPIVersion()
throws RemoteException;
/**
* Returns the implementation version for this <code>NetHandler</code>. Format is vendor specific.
*
* @return Implementation version of the <code>NetHandler</code> as a String.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public String getImplementationVersion()
throws RemoteException;
/**
* Registers a listener for <code>NetHandler</code> messaging events. Network Handler messaging
* events are sent from an entity in the network to an individual application on a
* host. Network messaging events can be broadcast to all hosts, a group of hosts,
* or sent to an individual host device. Please refer to the <code>NetworkMessageEvent</code> for
* a description of the message format.
* <br>
* If the <code>NetMessageListener listener</code> is currently registered by the calling application
* to receive <code>NetHandler</code> messaging events, then the call to <code>addMessageListener</code> returns
* the same value that references the currently registered listener. Each NetworkMessageEvent
* is only notified once to a registered <code>NetMessageListener</code> irrespective of the number of
* times that the listener has been registered in calls to <code>addMessageListener</code>.
*
* @param listener A listener.
*
* @return An integer identifier for this listener that can be used in a subsequent
* call to <code>removeMessageListener</code>.
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public int addMessageListener(NetMessageListener listener)
throws RemoteException;
/**
* Removes a listener from the list of those receiving network message events. An
* integer <code>listenerId</code> is used instead of a reference to the <code>NetMessageListener</code>
* in order to avoid potential problems with identifying the listener when
* this interface is used with IXC. This method does nothing if the <code>listenerID</code> does
* not refer to a currently registered <code>NetMessageListener</code> associated with the calling application.
*
* @param listenerId An integer that identifies the listener to be removed.
* Should be the return value from a previous call to <code>addMessaageListener()</code>.
* An integer <code>listenerId</code> is used instead of the listener itself because of
* uncertainty about object identity when this interface is accessed via IXC.
*
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public void removeMessageListener(int listenerId)
throws RemoteException;
/**
* Returns a collection of vendor specific attributes. This is intended to include
* identifiers like the hub id, channel map id and controller id that can be
* useful in filtering localized data as well as field that can be useful for diagnostic
* purposes.
*
* @return A <code>Properties</code> object containing all attributes.
*/
public Properties getAttributes();
/**
* Returns the value of a single vendor specific attributes. This is intended to include
* identifiers like the hub id, channel map id and controller id that can be
* useful in filtering localized data as well as fields that can be useful for diagnostic
* purposes.
*
* @param attributeName The name of the requested attribute.
* @return A <code>String</code> representation of the attribute value or null if the requested
* attribute does not exist.
*/
public String getAttribute(String attributeName);
/**
* Indicates the current state of the Network Handler and if it is ready for operation.
* The state returned SHALL be one of the following constant values defined in the <code>NetHandler</code> interface.
* <ul>
* <li> <code>NH_INITIALIZING</code> the Network handler is in the process of initializing and is not ready to process requests.
* <li> <code>NH_READY</code> the Network handler is ready to process requests
* <li> <code>NH_ERROR_START</code> The start of a range of error codes indicating that the Network handler has encountered an
* error and cannot process requests. The meaning of each error code is implementation specific.
* <li> <code>NH_ERROR_END</code> The end of a range of error codes indicating that the Network handler has encountered an error
* and cannot process requests. The meaning of each value within this range is implementation specific.
* </ul>
*
* @return The current state of the Network Handler, which SHALL be one of the
* <code>NH_*</code> constants defined in this class.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public int getState()
throws RemoteException;
/**
* Adds a <code>NetHandlerStateListener</code> that is notified with <code>NetHandlerStateEvents</code>
* when the <code>NetHandler</code> state changes.
* <br>
* If the <code>NetHandlerStateListener</code> listener is currently registered by the calling
* application to receive <code>NetHandlerStateEvents</code>, then the call to <code>addStateListener</code>
* returns the same value that references the currently registered listener. Each
* <code>NetworkHandlerStateEvent</code> is only notified once to a registered <code>NetHandlerStateListener</code>
* irrespective of the number of times that the listener has been registered in calls to <code>addStateListener</code>.
*
* @param listener Listener to be added.
* @return An integer that identifies this listener can can be used to remove the
* listener in a subsequent call to the <code>removeStateListener</code> method.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public int addStateListener(NetHandlerStateListener listener)
throws RemoteException;
/**
* Removes a <code>NetHandlerStateListener</code> that was previously registered with the
* <code>addStateListener</code> method. This method does nothing if the <code>listenerID</code> does
* not refer to a currently registered <code>NetHandlerStateListener</code> associated with the calling application.
*
* @param listenerID The integer listener id that was returned in a previous call
* to <code>addStateListener</code>. An integer <code>listenerId</code> is used instead of the listener itself
* because of uncertainty about object identity when this interface is accessed via IXC.
* @throws RemoteException Thrown if there is problem with IXC communication.
*/
public void removeStateListener(int listenerID)
throws RemoteException;
}
// COPYRIGHT HEADER
//------------------------------------------------------------
// Copyright © 2007 Time Warner Cable, Inc.
//
//
// This module contains unpublished, confidential, proprietary
// material. The use and dissemination of this material are
// governed by a license. The above copyright notice does not
// evidence any actual or intended publication of this material.
//
// Created:
// File: NetHandlerStateEvent.java
//------------------------------------------------------------
// COPYRIGHT END
package com.opencable.handler.nethandler;
import java.util.EventObject;
import com.opencable.handler.nethandler.NetHandler;
/**
* An event that is delivered to <code>NetHandlerStateListeners</code> when the <code>NetHandler</code>
* state changes. Note that the <code>EventObject.getSource()</code> method returns null
* once this object has been passed across an IXC interface.
*/
public final class NetHandlerStateEvent extends EventObject
{
// Serialization UID should NOT be changed when fields are added to this class.
static final long serialVersionUID = -5957311033077765075L;
private int m_newState;
/**
* Constructs a new <code>NetHandlerStateEvent</code>
*
* @param source The <code>NetHandler</code> that is the source of the event.
* @param newState The new state of the <code>NetHandler</code>, which SHALL be one of the
* <code>NH_*</code> constants defined in the <code>NetHandler</code> interface.
*/
public NetHandlerStateEvent(NetHandler source, int newState)
{
super(source);
m_newState = newState;
}
/**
* The new state of the <code>NetHandler</code>, which SHALL be one of the <code>NH_*</code> constants defined