/*
 * Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies). 
 * All rights reserved.
 * This component and the accompanying materials are made available
 * under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *
 * Initial Contributors:
 * Nokia Corporation - initial contribution.
 *
 * Contributors:
 *
 * Description:
 *
 */

package com.nokia.traceviewer.api;

import java.util.ArrayList;

import com.nokia.traceviewer.api.TraceViewerAPI.TVAPIError;
import com.nokia.traceviewer.engine.TraceInformation;
import com.nokia.traceviewer.engine.TraceMetaData;
import com.nokia.traceviewer.engine.activation.TraceActivationComponentItem;
import com.nokia.traceviewer.engine.dataprocessor.DataProcessor;
import com.nokia.traceviewer.internal.api.TraceViewerAPI2Impl;

/**
 * Public API access point to TraceViewer API functions that offers the
 * following enhancements to the original <code>TraceViewerAPI</code>
 * implementation: - notification services for client on connection status
 * changes. - keeps count of active clients, and disconnects data source only
 * when there is no more active clients.
 * 
 * Public API calls are further delegated to internal implementation of the API
 * in <code>TraceViewerAPIImpl2</code> class.
 * 
 * Other API services that are not connectivity related are just delegated to
 * original <code>TraceViewerAPI</code> implementation.
 * 
 * @see TraceViewerAPI2Impl
 * @see TraceViewerAPI
 */
public class TraceViewerAPI2 {

	/**
	 * Connect using current settings defined in TraceViewer's preferences.
	 * Client is registered successfully in case no exceptions are thrown.
	 * 
	 * @param client
	 *            client requesting the connection.
	 * @return connection info about the connected service.
	 * @throws TraceConnectivityException
	 * @see TraceConnectivityException
	 */
	public static ITraceConnInfo connect(ITraceConnClient client)
			throws TraceConnectivityException {
		return TraceViewerAPI2Impl.connect(client);
	}

	/**
	 * Connects using current settings defined in TraceViewer's preferences
	 * Client is disconnected and unregistered successfully for notifications in
	 * case no exceptions are thrown.
	 * 
	 * @param client
	 *            client requesting the connection.
	 * @throws TraceConnectivityException
	 * @see TraceConnectivityException
	 */
	public static void disconnect(ITraceConnClient client)
			throws TraceConnectivityException {
		TraceViewerAPI2Impl.disconnect(client);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#activateTraces(int, int[],
	 *      boolean)
	 * 
	 * @param componentId
	 *            component ID
	 * @param groupIds
	 *            group ID array
	 * @param activate
	 *            if true, activate. If false, deactivate
	 * @return error code from TVAPIError
	 * @throws TraceConnectivityException
	 */
	public static TVAPIError activateTraces(int componentId, int[] groupIds,
			boolean activate) throws TraceConnectivityException {
		TVAPIError error = TraceViewerAPI.activateTraces(componentId, groupIds,
				activate);
		if (error == TVAPIError.NOT_CONNECTED) {
			throw new TraceConnectivityException(error);
		}
		return error;
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#activateTraces(int,
	 *      java.lang.String[], boolean)
	 * 
	 * @param componentId
	 *            component ID
	 * @param groupNames
	 *            array of group names
	 * @param activate
	 *            if true, activate. If false, deactivate.
	 * @return error code from TraceViewerAPI
	 * 
	 * @throws TraceConnectivityException
	 */
	public static TVAPIError activateTraces(int componentId,
			String[] groupNames, boolean activate)
			throws TraceConnectivityException {
		TVAPIError error = TraceViewerAPI.activateTraces(componentId,
				groupNames, activate);
		if (error == TVAPIError.NOT_CONNECTED) {
			throw new TraceConnectivityException(error);
		}
		return error;
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#addDataProcessor(com.nokia.traceviewer.engine.dataprocessor.DataProcessor,
	 *      com.nokia.traceviewer.api.DPLocation, int)
	 * 
	 * @param dataProcessor
	 *            the dataprocessor to be added
	 * @param location
	 *            location in the list
	 * @param priority
	 *            priority of the dataprocessor. If two dataprocessors are in
	 *            the same location in the dataprocessor list, the one with
	 *            higher priority will be run first
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError addDataProcessor(DataProcessor dataProcessor,
			DPLocation location, int priority) {
		return TraceViewerAPI.addDataProcessor(dataProcessor, location,
				priority);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getDictionaryComponents()
	 * 
	 * @return list of components from all loaded Dictionaries. List can be
	 *         empty.
	 */
	public static ArrayList<TraceActivationComponentItem> getDictionaryComponents() {
		return TraceViewerAPI.getDictionaryComponents();
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getTraceComponentName(int)
	 * 
	 * @param componentId
	 *            component ID
	 * @return component name or null if not found or no Decode files are loaded
	 */
	public static String getTraceComponentName(int componentId) {
		return TraceViewerAPI.getTraceComponentName(componentId);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getTraceGroupId(int,
	 *      java.lang.String)
	 * 
	 * @param componentId
	 *            component ID
	 * @param groupName
	 *            the group name
	 * @return trace group ID or -1 if group ID not found or -2 if no Decode
	 *         files are loaded
	 */
	public static int getTraceGroupId(int componentId, String groupName) {
		return TraceViewerAPI.getTraceGroupId(componentId, groupName);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getTraceGroupName(int, int)
	 * 
	 * @param componentId
	 *            component ID
	 * @param groupId
	 *            group ID
	 * @return group name or null if not found or no Decode files are loaded
	 */
	public static String getTraceGroupName(int componentId, int groupId) {
		return TraceViewerAPI.getTraceGroupName(componentId, groupId);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getTraceName(int, int, int)
	 * 
	 * @param componentId
	 *            component ID
	 * @param groupId
	 *            group ID
	 * @param traceId
	 *            trace ID
	 * @return trace name or null if not found or no Decode files are loaded
	 */
	public static String getTraceName(int componentId, int groupId, int traceId) {
		return TraceViewerAPI.getTraceName(componentId, groupId, traceId);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#getTraceMetaData(com.nokia.traceviewer.engine.TraceInformation)
	 * 
	 * @param information
	 *            TraceInformation to be used when finding correct metadata
	 * @return trace metadata or null if nothing is found
	 */
	public static TraceMetaData getTraceMetaData(TraceInformation information) {
		return TraceViewerAPI.getTraceMetaData(information);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#loadDecodeFile(java.lang.String,
	 *      boolean)
	 * 
	 * @param decodeFilePath
	 *            absolute path to the decode file. Path must be in correct
	 *            format for any operating system (Windows, Linux)
	 * @param deleteExistingModel
	 *            if true, old decode model is removed before this decode file
	 *            is loaded
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError loadDecodeFile(String decodeFilePath,
			boolean deleteExistingModel) {
		return TraceViewerAPI.loadDecodeFile(decodeFilePath,
				deleteExistingModel);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#openLogFile(java.lang.String)
	 * 
	 * @param filePath
	 *            file path to open. If file path ends with .txt, file is opened
	 *            as ASCII log. If filePath is null and TraceViewer view is
	 *            open, a file selection dialog is opened.
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError openLogFile(String filePath) {
		return TraceViewerAPI.openLogFile(filePath);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#removeDataProcessor(com.nokia.traceviewer.engine.dataprocessor.DataProcessor)
	 * @param dataProcessor
	 *            the DataProcessor to be removed
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError removeDataProcessor(DataProcessor dataProcessor) {
		return TraceViewerAPI.removeDataProcessor(dataProcessor);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#saveCurrentTracesToLog(java.lang.String)
	 * @param filePath
	 *            file path where to save the log. If null and TraceViewer view
	 *            is visible, a file selection dialog is shown
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError saveCurrentTracesToLog(String filePath) {
		return TraceViewerAPI.saveCurrentTracesToLog(filePath);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#sendDataToDeviceWithHeader(byte
	 *      [], boolean)
	 * 
	 * @param msg
	 *            byte array to be sent
	 * @param changeMediaType
	 *            If true, changes media type to the header when sending the
	 *            message. Otherwise leaves the message as it is.
	 * @return error code from TraceViewerAPI
	 * @throws TraceConnectivityException
	 */
	public static TVAPIError sendDataToDeviceWithHeader(byte[] msg,
			boolean changeMediaType) throws TraceConnectivityException {
		TVAPIError error = TraceViewerAPI.sendDataToDeviceWithHeader(msg,
				changeMediaType);
		if (error == TVAPIError.NOT_CONNECTED) {
			throw new TraceConnectivityException(error);
		}
		return error;
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#sendDataToDeviceWithoutHeader
	 *      (byte[], byte)
	 * 
	 * @param msg
	 *            byte array to be sent
	 * @param messageId
	 *            messageID to add to the header. Might not be needed, depends
	 *            on the protocol.
	 * @return error code from TraceViewerAPI
	 * @throws TraceConnectivityException
	 */
	public static TVAPIError sendDataToDeviceWithoutHeader(byte[] msg,
			byte messageId) throws TraceConnectivityException {
		TVAPIError error = TraceViewerAPI.sendDataToDeviceWithoutHeader(msg,
				messageId);
		if (error == TVAPIError.NOT_CONNECTED) {
			throw new TraceConnectivityException(error);
		}
		return error;
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#stopViewUpdate(boolean)
	 * 
	 * @param stop
	 *            if true, stops the view update. If false, restarts the update.
	 */
	public static void stopViewUpdate(boolean stop) {
		TraceViewerAPI.stopViewUpdate(stop);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#syncToTimestamp(java.lang.String,
	 *      java.lang.String)
	 * 
	 * @param startTimestamp
	 *            start timestamp in the format of hh:mm:ss.SSS
	 * @param endTimestamp
	 *            end timestamp in the format of hh:mm:ss.SSS or null if only
	 *            start timestamp is searched for
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError syncToTimestamp(String startTimestamp,
			String endTimestamp) {
		return TraceViewerAPI.syncToTimestamp(startTimestamp, endTimestamp);
	}

	/**
	 * @see com.nokia.traceviewer.api.TraceViewerAPI#syncToTrace(int, int)
	 * 
	 * @param startTrace
	 *            start trace number
	 * @param endTrace
	 *            end trace number of 0 if only start trace is searched for
	 * @return error code from TraceViewerAPI
	 */
	public static TVAPIError syncToTrace(int startTrace, int endTrace) {
		return TraceViewerAPI.syncToTrace(startTrace, endTrace);
	}

}