org.restcomm.media.control.mgcp.call.MgcpCall Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mgcp2 Show documentation
There is a newer version: 7.0.16
/*
 * TeleStax, Open Source Cloud Communications
 * Copyright 2011-2016, Telestax Inc and individual contributors
 * by the @authors tag. 
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.restcomm.media.control.mgcp.call;

import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Set;

import org.apache.log4j.Logger;

import com.google.common.collect.HashMultimap;
import com.google.common.collect.Multimaps;
import com.google.common.collect.SetMultimap;

/**
 * A Call is responsible to group Connections that belong to the same session.
 * 
 * The concept of Call has little semantic meaning in the MGCP protocol. However, it can be used to identify calls for reporting
 * and accounting purposes. It does not affect the handling of connections by the gateway.
 * 
 * 
 * Calls are identified by unique identifiers, independent of the underlying platforms or agents.

 * Call identifiers are hexadecimal strings, which are created by the Call Agent. The maximum length of call identifiers is 32
 * characters.
 * 
 * 
 * @author Henrique Rosa ([email protected])
 *
 */
public class MgcpCall {

    private static final Logger log = Logger.getLogger(MgcpCall.class);

    private final int callId;
    private final SetMultimap entries;

    public MgcpCall(int callId) {
        this.callId = callId;
        this.entries = Multimaps.synchronizedSetMultimap(HashMultimap. create(3, 3));
    }

    /**
     * Gets the call identifier.
     * 
     * @return The call identifier in base 10.
     */
    public int getCallId() {
        return callId;
    }

    /**
     * Gets the call identifier.
     * 
     * @return The call identifier in base 16.
     */
    public String getCallIdHex() {
        return Integer.toHexString(this.callId).toUpperCase();
    }

    /**
     * Gets the list of currently registered endpoints that own the connections in the Call.
     * 
     * @return An unmodifiable set of endpoint identifiers. If no endpoints are registered, an empty set is returned.
     */
    public Set getEndpoints() {
        return Collections.unmodifiableSet(this.entries.keySet());
    }

    /**
     * Gets the list of currently registered connections in the Call.
     * 
     * @return An unmodifiable set of connection identifiers. If no connections are registered, an empty set is returned.
     */
    public Set getConnections(String endpointId) {
        return Collections.unmodifiableSet(this.entries.get(endpointId));
    }

    /**
     * Registers a connection in the call.
     * 
     * @param endpointId The identifier of the endpoint that owns the connection.
     * @param connectionId The connection identifier.
     * @return Returns true if connection was successfully registered. Returns false otherwise.
     */
    public boolean addConnection(String endpointId, int connectionId) {
        boolean added = this.entries.put(endpointId, connectionId);
        if (added && log.isDebugEnabled()) {
            int left = this.entries.get(endpointId).size();
            log.debug("Call " + getCallIdHex() + " registered connection " + Integer.toHexString(connectionId) + " at endpoint " + endpointId + ". Connection count: " + left);
        }
        return added;
    }

    /**
     * Unregisters a connection from the call.
     * 
     * @param endpointId The identifier of the endpoint that owns the connection.
     * @param connectionId The connection identifier.
     * @return Returns true if connection was removed successfully. Returns false otherwise.
     */
    public boolean removeConnection(String endpointId, int connectionId) {
        boolean removed = this.entries.remove(endpointId, connectionId);
        if (removed && log.isDebugEnabled()) {
            int left = this.entries.get(endpointId).size();
            log.debug("Call " + getCallIdHex() + " unregistered connection " + Integer.toHexString(connectionId) + " from endpoint " + endpointId + ". Connection count: " + left);
        }
        return removed;
    }

    /**
     * Unregisters all connections that belong to an endpoint.
     * 
     * @param endpointId The identifier of the endpoint that owns the connections.
     * @return A set containing all unregistered connection identifiers. Returns an empty set if no connections exist.
     */
    public Set removeConnections(String endpointId) {
        Set removed = this.entries.removeAll(endpointId);
        if (!removed.isEmpty() && log.isDebugEnabled()) {
            log.debug("Call " + getCallIdHex() + " unregistered connections " + Arrays.toString(convertToHex(removed)) + " from endpoint " + endpointId);
        }
        return removed;
    }

    private String[] convertToHex(Collection identifiers) {
        String[] converted = new String[identifiers.size()];
        int index = 0;
        for (int id : identifiers) {
            converted[index] = Integer.toHexString(id);
            index++;
        }
        return converted;
    }

}