/*
 * Copyright (c) {YEAR}, {Company}
 * All rights reserved.
 */
 package {packageName}.implementation;

import java.util.Hashtable;

import javax.cim.CIMInstance;
import javax.cim.CIMObjectPath;
import javax.wbem.WBEMException;

import {packageName}.common.BaseCommon;
import {packageName}.common.CustomCloseableIterator;
import {packageName}.common.ReferenceInfo;

/**
 * This interface is used to allow a provider to be called for instance ops
 * functions, the generic arguments are used to constrain the data passed
 * into the generateXXX functions. This provides compile time type checking.
 */

public interface InstrumentationInterface<T extends BaseCommon, V extends BaseCommon> {

	/**
	 * Delete the specified instance
	 * 
	 * @param op
	 *            Points to the instance to delete.
	 * @throws WBEMException
	 */
	public void deleteInstance(CIMObjectPath op) throws WBEMException;

	/**
	 * will retrieve all the instance or objectpaths (depending on the value of
	 * "isObjectPath" property) that match the deviceID and systemName values
	 * passed in. If either of the values passed in are null, those values will
	 * not be checked for a match
	 * 
	 * @param iter
	 *            the iterator to add the values to
	 * @param op
	 *            this objectpath will be used to help create the returned
	 *            objectpath (i.e. the namespace, etc)
	 * @param localOnly
	 *            whether to return all the properties or just the local
	 *            properties
	 * @param includeClassOrigin
	 *            whether to return the class origin or not
	 * @param propertyList
	 *            a list of the properties to return
	 * @param filterQueryLanguage
	 *            language used to filter the return results on
	 * @param filterQuery
	 *            query used to filter the results on
	 * @param continueOnError
	 *            whether to continue if there is an error
	 * @param isObjectPath
	 *            if true only return CIMObjectPaths, otherwise return instances
	 * @param pDeviceID
	 *            if non-null, only return objects that have the matching
	 *            deviceID value
	 * @param pSysName
	 *            if non-null, only return objects that have the matching
	 *            SystemName value
	 * @throws WBEMException
	 */
	public void enumerate(CustomCloseableIterator<?> iter, CIMObjectPath op,
			boolean localOnly, boolean includeClassOrigin,
			String[] propertyList, String filterQueryLanguage,
			String filterQuery, boolean continueOnError, boolean isObjectPath,
			final Hashtable<String, Object> expectedValues,
			ReferenceInfo refInfo) throws WBEMException;

	/**
	 * returns the instance which matches the passed in objectpath
	 * 
	 * @param op
	 *            The objectpath that points to the instance we want
	 * @param localOnly
	 *            localonly
	 * @param includeClassOrigin
	 *            classorigin
	 * @param propertyList
	 *            null for all properties or a list of properties to return
	 * @return a CIMInstance representing the instance
	 * @throws WBEMException
	 */
	public CIMInstance getInstance(CIMObjectPath op, boolean localOnly,
			boolean includeClassOrigin, String[] propertyList)
			throws WBEMException;

	/**
	 * Check if an instance exists or not.
	 * 
	 * @param op
	 *            The objectpath of the instance to look for
	 * @return true if it exists, false otherwise
	 * @throws WBEMException
	 *             Thrown only if an error other then CIM_ERR_NOT_FOUND is
	 *             retrieved.
	 */
	public boolean instanceExists(CIMObjectPath op) throws WBEMException;

	/**
	 * Used to modify the instance
	 * 
	 * @param ci
	 *            Instance with changed properties
	 * @param propertyList
	 *            List of properties that have changed (null for all)
	 * @throws WBEMException
	 */
	public void modifyInstance(CIMInstance ci, String[] propertyList)
			throws WBEMException;

	/**
	 * Used to generate an instance of the class using the common class(es)
	 * passed in
	 *
	 * @param pOP
	 *		The ObjectPath which has the namespace and other information
	 * @param localOnly
	 *            localonly
	 * @param includeClassOrigin
	 *            classorigin
	 * @param propertyList
	 *            null for all properties or a list of properties to return
	 * @param commomParam1
	 *			  The first common object
	 * @param commonParam2
	 *			  The second common object
	 * @param o
	 *			  var args which can contain any special data the function needs
	 * @return a CIMInstance representing the instance
	 */
	public CIMInstance generateInstance(CIMObjectPath pOP, boolean localOnly,
			boolean includeClassOrigin, String[] propertyList,
			T commonParam1, V commonParam2, Object... o)
			throws WBEMException;

				/**
	 * Used to generate an instance of the class using the common class(es)
	 * passed in
	 *
	 * @param pOP
	 *		The ObjectPath which has the namespace and other information
	 * @param commomParam1
	 *			  The first common object
	 * @param commonParam2
	 *			  The second common object
	 * @param o
	 *			  var args which can contain any special data the function needs
	 * @return a CIMInstance representing the instance
	 */
	public CIMObjectPath generateObjectPath(CIMObjectPath pOP,
			T commonParam1, V commonParam2, Object... o)
			throws WBEMException;
}
