ConfigurationAdminMBean.java

/*
 * Copyright (c) OSGi Alliance (2009, 2010). All Rights Reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.osgi.jmx.service.cm;

import java.io.IOException;

import javax.management.openmbean.TabularData;

import org.osgi.jmx.JmxConstants;

/**
 * This MBean provides the management interface to the OSGi Configuration
 * Administration Service.
 * 
 * @version $Revision$
 * @ThreadSafe
 */
public interface ConfigurationAdminMBean {
	/**
	 * The object name for this mbean.
	 */
	String OBJECTNAME = JmxConstants.OSGI_COMPENDIUM+":service=cm,version=1.3";

	/**
	 * Create a new configuration instance for the supplied persistent id of the
	 * factory, answering the PID of the created configuration
	 * 
	 * @param factoryPid the persistent id of the factory
	 * @return the PID of the created configuration
	 * @throws IOException if the operation failed
	 */
	String createFactoryConfiguration(String factoryPid) throws IOException;

	/**
	 * Create a factory configuration for the supplied persistent id of the
	 * factory and the bundle location bound to bind the created configuration
	 * to, answering the PID of the created configuration
	 * 
	 * @param factoryPid the persistent id of the factory
	 * @param location the bundle location
	 * @return the pid of the created configuation
	 * @throws IOException if the operation failed
	 */
	String createFactoryConfigurationForLocation(String factoryPid, String location)
			throws IOException;

	/**
	 * Delete the configuration
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @throws IOException if the operation fails
	 */
	void delete(String pid) throws IOException;

	/**
	 * Delete the configuration
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param location the bundle location
	 * @throws IOException if the operation fails
	 */
	void deleteForLocation(String pid, String location) throws IOException;

	/**
	 * Delete the configurations matching the filter specification.
	 * 
	 * @param filter the string representation of the
	 *        <code>org.osgi.framework.Filter</code>
	 * @throws IOException if the operation failed
	 * @throws IllegalArgumentException if the filter is invalid
	 */
	void deleteConfigurations(String filter) throws IOException;

	/**
	 * Answer the bundle location the configuration is bound to
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @return the bundle location
	 * @throws IOException if the operation fails
	 */
	String getBundleLocation(String pid) throws IOException;

	/**
	 * Answer the factory PID if the configuration is a factory configuration,
	 * null otherwise.
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @return the factory PID
	 * @throws IOException if the operation fails
	 */
	String getFactoryPid(String pid) throws IOException;

	/**
	 * Answer the factory PID if the configuration is a factory configuration,
	 * null otherwise.
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param location the bundle location
	 * @return the factory PID
	 * @throws IOException if the operation fails
	 */
	String getFactoryPidForLocation(String pid, String location) throws IOException;

	/**
	 * Answer the contents of the configuration <p/>
	 * 
	 * @see JmxConstants#PROPERTIES_TYPE for the details of the TabularType
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @return the table of contents
	 * @throws IOException if the operation fails
	 */

	TabularData getProperties(String pid) throws IOException;

	/**
	 * Answer the contents of the configuration <p/>
	 * 
	 * @see JmxConstants#PROPERTIES_TYPE for the details of the TabularType
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param location the bundle location
	 * @return the table of contents
	 * @throws IOException if the operation fails
	 */
	TabularData getPropertiesForLocation(String pid, String location) throws IOException;

	/**
	 * Answer the list of PID/Location pairs of the configurations managed by
	 * this service
	 * 
	 * @param filter the string representation of the
	 *        <code>org.osgi.framework.Filter</code>
	 * @return the list of configuration PID/Location pairs
	 * @throws IOException if the operation failed
	 * @throws IllegalArgumentException if the filter is invalid
	 */
	String[][] getConfigurations(String filter) throws IOException;

	/**
	 * Set the bundle location the configuration is bound to
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param location the bundle location
	 * @throws IOException if the operation fails
	 */
	void setBundleLocation(String pid, String location) throws IOException;

	/**
	 * Update the configuration with the supplied properties For each property
	 * entry, the following row is supplied <p/>
	 * 
	 * @see JmxConstants#PROPERTIES_TYPE for the details of the TabularType
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param properties the table of properties
	 * @throws IOException if the operation fails
	 */
	void update(String pid, TabularData properties) throws IOException;

	/**
	 * Update the configuration with the supplied properties For each property
	 * entry, the following row is supplied <p/>
	 * 
	 * @see JmxConstants#PROPERTIES_TYPE for the details of the TabularType
	 * 
	 * @param pid the persistent identifier of the configuration
	 * @param location the bundle location
	 * @param properties the table of properties
	 * @throws IOException if the operation fails
	 */
	void updateForLocation(String pid, String location, TabularData properties)
			throws IOException;
}