/*
v * (C) Copyright 2013 Kurento (http://kurento.org/)
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the GNU Lesser General Public License
* (LGPL) version 2.1 which accompanies this distribution, and is available at
* http://www.gnu.org/licenses/lgpl-2.1.html
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
*/
package com.kurento.kmf.content;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.kurento.kmf.common.exception.KurentoMediaFrameworkException;
/**
*
* Defines the events associated to the handler entity.
*
* @author Luis López (llopez@gsyc.es)
* @author Miguel París (mparisdiaz@gsyc.es)
* @author Boni García (bgarcia@gsyc.es)
* @version 1.0.0
*/
public abstract class ContentHandler<T extends ContentSession> {
private static final Logger log = LoggerFactory
.getLogger(ContentHandler.class);
/**
* Invoked by the framework when a request is received from a client for
* sending/receiving content
*
* @param contentSession
* session associated to the request automatically created by the
* framework
* @throws Exception
* possible exception thrown by handler implementation
*/
public abstract void onContentRequest(T contentSession) throws Exception;
/**
* Invoked by the framework when the content exchange really starts. For
* example, in an HttpPlayerService, this methods is invoked when the
* HttpEndpoint really receives the media request from the client
*
* @param contentSession
* the session for which the content exchange started
* @throws Exception
* possible exception thrown by handler implementation
*/
public void onContentStarted(T contentSession) throws Exception {
getLogger().info(
"Call to default onContentStarted in session "
+ contentSession.getContentId());
}
/**
* Invoked by the framework when a ContentSession successfully concludes.
* This method is invoked if the end-client request and explicit termination
* of the session.
*
* @param contentSession
* the ContentSession completing its job
* @throws Exception
* possible exception thrown by handler implementation
*/
public void onSessionTerminated(T contentSession, int code, String reason)
throws Exception {
getLogger().info(
"Call to default onSessionTerminated in session "
+ contentSession.getContentId());
}
/**
* Invoked by the framework when a ContentSession receives a user defined
* command from the client.
*
* @param contentSession
* The ContentSession receiving the command
* @param contentCommand
* The command received from client
* @throws Exception
* possible exception thrown by handler implementation
*/
public ContentCommandResult onContentCommand(T contentSession,
ContentCommand contentCommand) throws Exception {
throw new KurentoMediaFrameworkException(
"Handler must implement onContentCommand for being able to receive commands;",
10026);
}
/**
* Invoked by the framework when a session enters into an error condition
* due to an asynchronous media server error. The invocation of this method
* always implies the invalidation of the session and the conclusion of the
* content exchange. This method is not invoked if the content session is
* explicitly terminated by invoking its terminate method.
*
* @param contentSession
* The ContentSession receiving the error
* @param code
* The return code coming from the Media Server
* @param description
* A description of the error.
* @throws Exception
*/
public void onSessionError(T contentSession, int code, String description)
throws Exception {
log.error(description);
}
/**
* This method is invoked every time the handler implementation throws and
* exception which is not caught by the handler itself. In other words, when
* an exception is thrown to the Content API framework by the handler. It is
* important to remark that if this method throws an exception itself, it
* will produce a recursive call which may drive to abnormal program
* termination. The invocation of this method does not imply the
* invalidation of the session.
*
* TODO: explain what the default implementation makes
*
* @param contentSession
* @param exception
* @throws Exception
*/
public void onUncaughtException(T contentSession, Throwable exception)
throws Exception {
log.error(exception.getMessage(), exception);
int code = 9999;
if (exception instanceof KurentoMediaFrameworkException) {
code = ((KurentoMediaFrameworkException) exception).getCode();
}
contentSession.terminate(code, exception.getMessage());
}
protected Logger getLogger() {
return log;
}
}