/*
 * AssocProvImplIF.java
 *
 * Generated by {productTitle}  {versionName} - {utilityTitle}
 *
 * {copywrite}
 */
package {packageName}.common;

import javax.cim.CIMInstance;
import javax.cim.CIMObjectPath;
import javax.wbem.WBEMException;
import javax.wbem.WBEMOperation;
import javax.wbem.provider.PullAssociatorProvider;

import com.ws.wbem.CloseableAddableIterator;
import com.ws.wbem.query.fql.FQLParser;

/**
 * This interface is used to allow a provider to be called for Association
 * functions, the arguments are used to constrain the results and indicate which
 * association operation is being invoked.<BR>
 */
public interface AssocProvImplIF {

	/**
	 * This function handles the associators and associatorNames methods.
	 *
	 * @param iter
	 *            An object which represents where the instances/objectpaths
	 *            should be returned to.
	 * @param assocName
	 *            The name of the association class
	 * @param objectName
	 *            The Objectpath of which this function is being invoked.
	 * @param resultClass
	 *            The name of the class the caller is expecting to get back, or
	 *            null if it wants all.
	 * @param role
	 *            The name of the role the 'objectName' parameter plays in this
	 *            association, or null if it wants all.
	 * @param resultRole
	 *            The name of the role the caller is expecting to get back, or
	 *            null if it wants all.
	 * @param includeClassOrigin
	 *            The class origin attribute is the name of the class that first
	 *            defined the property. If true, the class origin attribute will
	 *            be present for each property on all returned CIMInstances. If
	 *            false, the class origin will not be present.
	 * @param propertyList
	 *            If the PropertyList input parameter is not NULL, the members
	 *            of the array define one or more Property names. Each returned
	 *            Instance MUST NOT include elements for any Properties missing
	 *            from this list. Note that if localOnly is specified as true
	 *            this acts as an additional filter on the set of Properties
	 *            returned (e.g. if Property A is included in the PropertyList
	 *            but localOnly is set to true and A is not local to a returned
	 *            Instance, then it will not be included in that Instance). If
	 *            the PropertyList input parameter is an empty array this
	 *            signifies that no Properties are included in each returned
	 *            Instance. If the PropertyList input parameter is NULL this
	 *            specifies that all Properties (subject to the conditions
	 *            expressed by the other parameters) are included in each
	 *            returned Instance. The PropertyList may contain duplicate or
	 *            invalid Property names. The Provider must ignore them but
	 *            otherwise process the request normally; i.e. the returned
	 *            Instance(s) will not contain duplicate or invalid Property
	 *            Names.
	 * @param fqlParser
	 *            FQLPraser object used to evaluate returned instances against
	 * @param continueOnError
	 *            Indicates if processing should continue even if an error
	 *            occurs
	 * @param wbemOperation
	 *            String which contains the WBEM operation
	 * @throws WBEMException
	 * @see {@link PullAssociatorProvider#associators(CIMObjectPath, CIMObjectPath, String, String, String, boolean, String[], String, String, boolean)}
	 * @see PullAssociatorProvider#associatorNames(CIMObjectPath, CIMObjectPath,
	 *      String, String, String, String, String, boolean)
	 */
	public void assocEnumerate(
			final CloseableAddableIterator<CIMInstance> iter,
			final CIMObjectPath assocName, final CIMObjectPath objectName,
			final String resultClass, final String role,
			final String resultRole, final String[] propertyList,
			final FQLParser fqlParser, final boolean continueOnError,
			final WBEMOperation wbemOperation) throws WBEMException;


	/**
	 * This function handles the references and referenceNames calls
	 *
	 * @param iter
	 *            An object which represents where the instances/objectpaths
	 *            should be returned to
	 * @param assocName
	 *            Defines the association that the objectName Object should be
	 *            associated to. The provider uses this information to identify
	 *            which association must be traversed in case it supports more
	 *            than one association.
	 * @param objectName
	 *            Defines the source CIM Object whose associated Objects are to
	 *            be returned. This is an Instance name (modelpath).
	 * @param role
	 *            The Role input parameter, if not NULL, MUST be a valid
	 *            Property name. It acts as a filter on the returned set of
	 *            Association Instances by mandating that each returned
	 *            Association Instance MUST refer to the target Instance in
	 *            which the target Instance plays the specified role (i.e. the
	 *            name of the Property in the Association Instance that refers
	 *            to the target Instance MUST match the value of this
	 *            parameter). Thus, if Role input parameter is set to
	 *            Antecedent, only Association Instances where target Instance
	 *            is the Antecedent reference are returned. NOTE: The target
	 *            Instance is the objectName input parameter.
	 * @param includeClassOrigin
	 *            The class origin attribute is the name of the class that first
	 *            defined the property or method. If true, the class Origin
	 *            attribute will be present for each property and method on all
	 *            Objects returned. If false, the class origin will not be
	 *            present.
	 * @param propertyList
	 *            If the PropertyList input parameter is not NULL, the members
	 *            of the array define one or more Property names. Each returned
	 *            Instance MUST NOT include elements for any Properties missing
	 *            from this list. Note that if LocalOnly is specified as true
	 *            this acts as an additional filter on the set of Properties
	 *            returned (e.g. if Property A is included in the PropertyList
	 *            but LocalOnly is set to true and A is not local to a returned
	 *            Instance, then it will not be included in that Instance). If
	 *            the PropertyList input parameter is an empty array this
	 *            signifies that no Properties are included in each returned
	 *            Instance. If the PropertyList input parameter is NULL this
	 *            specifies that all Properties (subject to the conditions
	 *            expressed by the other parameters) are included in each
	 *            returned Instance. The PropertyList may contain duplicate or
	 *            invalid Property names. The Provider must ignore them but
	 *            otherwise process the request normally; i.e. the returned
	 *            Instance(s) will not contain duplicate or invalid Property
	 *            Names.
	 * @param fqlParser
	 *            FQLPraser object used to evaluate returned instances against
	 * @param continueOnError
	 *            Indicates if processing should continue even if an error
	 *            occurs
	 * @param wbemOperation
	 *            the WBEM operation
	 * @throws WBEMException
	 * @see {@link PullAssociatorProvider#references(CIMObjectPath, CIMObjectPath, String, boolean, String[], String, String, boolean)}
	 * @see PullAssociatorProvider#referenceNames(CIMObjectPath, CIMObjectPath,
	 *      String, String, String, boolean)
	 */
	public void refEnumerate(final CloseableAddableIterator<CIMInstance> iter,
			final CIMObjectPath assocName, final CIMObjectPath objectName,
			final String role, final String[] propertyList,
			final FQLParser fqlParser, final boolean continueOnError,
			final WBEMOperation wbemOperation) throws WBEMException;
}