<commit_before>/*
 * $Header$
 * 
 * Copyright (c) OSGi Alliance (2005). 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.
 */

package org.osgi.application;

import java.util.Dictionary;
import java.util.Map;

import org.osgi.framework.Constants;
import org.osgi.framework.ServiceRegistration;


/**
 * <code>ApplicationContext</code> is the access point for an OSGi-aware
 * application to the features of the OSGi Service Platform. Each application
 * instance will have its own <code>ApplicationContext</code> instance, which
 * will not be reused after destorying the corresponding application instace.
 * <p>
 * Application instances can obtain their <code>ApplicationContext</code>
 * using the {@link Framework#getApplicationContext} method.
 * 
 * @see org.osgi.application.Framework
 */
public interface ApplicationContext {

    /**
     * Adds the specified {@link ApplicationServiceListener} object to this context
     * application instance's list of listeners. The specified <code>referenceName</code> is a 
     * reference name specified in the descriptor of the corresponding application. The registered
     * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred service.
     * <p>
     * If the <code>listener</code> was already added, calling this method will overwrite the previous
     * registration.
     * <p>
     * 
     * @param listener
     *            The {@link org.osgi.application.ApplicationServiceListener} to be added. It must
     *            not be <code>null</code>
     * @param referenceName the reference name of a service from the descriptor of the corresponding
     *            application. It must not be <code>null</code>.
     * @throws java.lang.IllegalStateException
     *             If this context application instance has stopped.
     * @throws java.lang.NullPointerException If <code>listener</code> or <code>referenceName</code>
     *             is <code>null</code>      
     * @throws java.lang.IllegalArgumentException If there is no service in the
     *             application descriptor with the specified <code>referenceName</code>.
     */
    public void addServiceListener(ApplicationServiceListener listener, String referenceName);

    /**
     * Adds the specified {@link ApplicationServiceListener} object to this context
     * application instance's list of listeners. The <code>referenceNames</code> parameter is an 
     * array of reference name specified in the descriptor of the corresponding application. The registered
     * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred 
     * services.
     * <p>
     * If the <code>listener</code> was already added, calling this method will overwrite the previous
     * registration.
     * <p><commit_msg>ADDED: throw<commit_after>/*
 * $Header$
 * 
 * Copyright (c) OSGi Alliance (2005). 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.
 */

package org.osgi.application;

import java.util.Dictionary;
import java.util.Map;

import org.osgi.framework.Constants;
import org.osgi.framework.ServiceRegistration;


/**
 * <code>ApplicationContext</code> is the access point for an OSGi-aware
 * application to the features of the OSGi Service Platform. Each application
 * instance will have its own <code>ApplicationContext</code> instance, which
 * will not be reused after destorying the corresponding application instace.
 * <p>
 * Application instances can obtain their <code>ApplicationContext</code>
 * using the {@link Framework#getApplicationContext} method.
 * 
 * @see org.osgi.application.Framework
 */
public interface ApplicationContext {

    /**
     * Adds the specified {@link ApplicationServiceListener} object to this context
     * application instance's list of listeners. The specified <code>referenceName</code> is a 
     * reference name specified in the descriptor of the corresponding application. The registered
     * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred service.
     * <p>
     * If the <code>listener</code> was already added, calling this method will overwrite the previous
     * registration.
     * <p>
     * 
     * @param listener
     *            The {@link org.osgi.application.ApplicationServiceListener} to be added. It must
     *            not be <code>null</code>
     * @param referenceName the reference name of a service from the descriptor of the corresponding
     *            application. It must not be <code>null</code>.
     * @throws java.lang.IllegalStateException
     *             If this context application instance has stopped.
     * @throws java.lang.NullPointerException If <code>listener</code> or <code>referenceName</code>
     *             is <code>null</code>      
     * @throws java.lang.IllegalArgumentException If there is no service in the
     *             application descriptor with the specified <code>referenceName</code>.
     */
    public void addServiceListener(ApplicationServiceListener listener, String referenceName) throws java.lang.IllegalArgumentException;

    /**
     * Adds the specified {@link ApplicationServiceListener} object to this context
     * application instance's list of listeners. The <code>referenceNames</code> parameter is an 
     * array of reference name specified in the descriptor of the corresponding application. The registered
     * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred 
     * services.
     * <p>
     * If the <code>listener</code> was already added, calling this method will overwrite the previous
     * registration.
     * <p>
{'fraction_non_alphanumeric': 0.08148876865059845, 'fraction_numerical': 0.0026233808821118218, 'mean_word_length': 3.4267053701015966, 'pattern_counts': {'":': 0, '<': 69, '<?xml version=': 0, '>': 73, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '533982', 'n_tokens_mistral': 1521, 'n_tokens_neox': 1467, 'n_words': 586}