/*******************************************************************************
* Copyright (c) 2005, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.equinox.app;
import java.util.Map;
import org.osgi.framework.Bundle;
import org.osgi.service.application.ApplicationDescriptor;
/**
* The context used to start an application.
* <p>
* This interface is not intended to be implemented by clients.
* </p>
* @since 1.0
* @noextend This interface is not intended to be extended by clients.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IApplicationContext {
/**
* A system property that may be set by an application to specify exit data
* for the application. The value of the property must be a <code>String</code>.
* <p>
* Typically applications do not need to set this property. If an error is detected
* while launching or running an application then the launcher will set this property
* automatically in order to display a message to the end user. An application may
* set this property for the following reasons:
* <ul>
* <li>To provide the command line arguments to relaunch the eclipse platform. See
* {@link IApplication#EXIT_RELAUNCH}</li>
* <li>To provide an error message that will be displayed to the end user. This will
* cause an error dialog to be displayed to the user, this option should not be used
* by headless applications.</li>
* <li>To suppress all error dialogs displayed by the launcher this property can be
* set to the empty <code>String</code>. This is useful for
* headless applications where error dialogs must never be displayed.</li>
* </ul>
* </p>
* @since 1.3
*/
public static final String EXIT_DATA_PROPERTY = "eclipse.exitdata"; //$NON-NLS-1$
/**
* A key used to store arguments for the application. The content of this argument
* is unchecked and should conform to the expectations of the application being invoked.
* Typically this is a <code>String</code> array.
* <p>
*
* If the map used to launch an application {@link ApplicationDescriptor#launch(Map)} does
* not contain a value for this key then command line arguments used to launch
* the platform are set in the arguments of the application context.
*/
public static final String APPLICATION_ARGS = "application.args"; //$NON-NLS-1$
/**
* Exit object that indicates the application result will be delivered asynchronously.
* This object must be returned by the method {@link IApplication#start(IApplicationContext)}
* for applications which deliver a result asynchronously with the method
* {@link IApplicationContext#setResult(Object, IApplication)}.
* @since 1.3
*/
public static final Object EXIT_ASYNC_RESULT = new Object();
/**
* The arguments used for the application. The arguments from
* {@link ApplicationDescriptor#launch(Map)} are used as the arguments
* for this context when an application is launched.
*
* @return a map of application arguments.
*/
public Map getArguments();
/**
* This method should be called once the application is completely initialized and running.
* This method will perform certain operations that are needed once an application is running.
* One example is bringing down a splash screen if it exists.
*/
public void applicationRunning();
/**
* Returns the application associated with this application context. This information
* is used to guide the runtime as to what application extension to create and execute.
*
* @return this product's application or <code>null</code> if none
*/
public String getBrandingApplication();
/**
* Returns the name of the product associated with this application context.
* The name is typically used in the title bar of UI windows.
*
* @return the name of the product or <code>null</code> if none
*/
public String getBrandingName();
/**
* Returns the text description of the product associated with this application context.
*
* @return the description of the product or <code>null</code> if none
*/
public String getBrandingDescription();
/** Returns the unique product id of the product associated with this application context.
*
* @return the id of the product
*/
public String getBrandingId();
/**
* Returns the property with the given key of the product associated with this application context.
* <code>null</code> is returned if there is no such key/value pair.
*
* @param key the name of the property to return
* @return the value associated with the given key or <code>null</code> if none
*/
public String getBrandingProperty(String key);
/**
* Returns the bundle which is responsible for the definition of the product associated with
* this application context.
* Typically this is used as a base for searching for images and other files
* that are needed in presenting the product.
*
* @return the bundle which defines the product or <code>null</code> if none
*/
public Bundle getBrandingBundle();
/**
* Sets the result of the application asynchronously. This method can only be used
* after the application's {@link IApplication#start(IApplicationContext) start}
* method has returned the value of {@link IApplicationContext#EXIT_ASYNC_RESULT}.
* <p>
* The specified application must be the same application instance which is
* associated with this application context. In other word the application instance
* for which {@link IApplication#start(IApplicationContext)} was called with this
* application context; otherwise an <code>IllegalArgumentException</code> is
* thrown.
* </p>
*
* @param result the result value for the application. May be null.
* @param application the application instance associated with this application context
* @throws IllegalStateException if {@link IApplicationContext#EXIT_ASYNC_RESULT} was
* not returned by the application's {@link IApplication#start(IApplicationContext) start}
* method or if the result has already been set for this application context.
* @throws IllegalArgumentException if the specified application is not the same
* application instance associated with this application context.
*
*
* @since 1.3
*/
public void setResult(Object result, IApplication application);
}