IPackageMemberMgr.java

/*******************************************************************************
 * Copyright (c) 2012 Arapiki Solutions Inc.
 * 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:
 *    psmith - initial API and 
 *        implementation and/or initial documentation
 *******************************************************************************/

package com.buildml.model;

import com.buildml.model.types.FileSet;
import com.buildml.model.types.ActionSet;

/**
 * The interface conformed-to by any PackageMemberMgr object, which represents a
 * subset of the functionality managed by a BuildStore object. A PackageMemberMgr
 * records which actions, file groups and sub packages belong inside each package.
 * <p>
 * There should be exactly one PackageMemberMgr object per BuildStore object. Use
 * the BuildStore's getPackageMemberMgr() method to obtain that one instance.
 * 
 * @author Peter Smith <psmith@arapiki.com>
 */
public interface IPackageMemberMgr {

	/**
	 * Numeric constants for type of package member.
	 */
	
	public static final int TYPE_ANY 			= 0;
	public static final int TYPE_FILE 			= 1;
	public static final int TYPE_FILE_GROUP 	= 2;
	public static final int TYPE_ACTION 		= 3;
	public static final int TYPE_SUB_PACKAGE 	= 4;
	
	/**
	 * Numeric constants for each of the scopes.
	 */
	public static final int SCOPE_NONE 			= 0;
	public static final int SCOPE_PRIVATE 		= 1;
	public static final int SCOPE_PUBLIC 		= 2;
	public static final int SCOPE_MAX 			= 2;

	/**
	 * Numeric constants describing the direction of neigbours
	 */
	public static final int NEIGHBOUR_ANY		= 0;
	public static final int NEIGHBOUR_LEFT		= 1;
	public static final int NEIGHBOUR_RIGHT		= 2;
	
	/**
	 * A helper class used to describe the package/scope that a member belongs to.
	 */
	public class PackageDesc {
		public int pkgId;
		public int pkgScopeId;
	}
	
	/**
	 * A helper class used to describe a package member's type, ID, and location.
	 */
	public class MemberDesc {
		public int memberType;
		public int memberId;
		public int x;
		public int y;
		
		public MemberDesc(int memberType, int memberId, int x, int y) {
			this.memberType = memberType;
			this.memberId = memberId;
			this.x = x;
			this.y = y;
		}
	}
	
	/**
	 * A helper class used to describe the location of a package's member.
	 */
	public class MemberLocation {
		public int x;
		public int y;
	}
	
	/**
	 * Given a scope's ID number, return the corresponding scope name.
	 * 
	 * @param id The scope's ID number.
	 * @return The scope's name, or null if the ID number is invalid.
	 */
	public abstract String getScopeName(int id);

	/**
	 * Given a scope's name, return its ID number. There can be many names for the same
	 * scope, so there isn't a 1:1 mapping of names to IDs. For example, both "private" and
	 * "priv" will return the same ID number.
	 * 
	 * @param name The scope's name.
	 * @return The scope's ID number, or ErrorCode.NOT_FOUND if the scope name isn't valid.
	 */
	public abstract int getScopeId(String name);

	/**
	 * Parse a package specification string, and return the ID of the package and
	 * (optionally) the ID of the scope within that package. The syntax of the package
	 * spec must be of the form:
	 *  <ol>
	 * 	  <li><pkg-name></li>
	 * 	  <li><pkg-name>/<scope-name></li>
	 *  </ol>
	 * That is, the scope name is optional.
	 * 
	 * @param pkgSpec The package specification string.
	 * @return An Integer[2] array, where [0] is the package's ID and [1] is the scope
	 * ID. If either portion of the pkgSpec was invalid (not a registered package or scope),
	 * the ID for that portion will be ErrorCode.NOT_FOUND. If there was no scope name
	 * specified, the scope ID will be 0, which represents the "None" scope.
	 */
	public abstract PackageDesc parsePkgSpec(String pkgSpec);

	/**
	 * Set the package/scope for a specific package member (file, file group, action, sub-package).
	 * 
	 * @param memberType 	The type of the member (MEMBER_TYPE_FILE, etc).
	 * @param memberId		The ID of the member (as defined in fileMgr, actionMgr, etc).
	 * @param pkgId			The package to add the member into.
	 * @param pkgScopeId	The scope (within the package) to add the member into. Only useful for MEMBER_TYPE_FILE.
	 * @return 	ErrorCode.OK on success, ErrorCode.NOT_FOUND if the member isn't defined, ErrorCode.BAD_VALUE
	 *          if the pkgId/pkgScopeId values are wrong, or ErrorCode.OUT_OF_RANGE if the member is not
	 *          within an appropriate range (such as within a package root).
	 */
	public abstract int setPackageOfMember(int memberType, int memberId, int pkgId, int pkgScopeId);
	
	/**
	 * Set the package/scope for a specific package member (file, file group, action, sub-package), using
	 * the scope of SCOPE_NONE.
	 * 
	 * @param memberType 	The type of the member (MEMBER_TYPE_FILE, etc).
	 * @param memberId		The ID of the member (as defined in fileMgr, actionMgr, etc).
	 * @param pkgId			The package to add the member into.
	 * @return 	ErrorCode.OK on success, ErrorCode.NOT_FOUND if the member isn't defined, ErrorCode.BAD_VALUE
	 *          if the pkgId/pkgScopeId values are wrong, or ErrorCode.OUT_OF_RANGE if the member is not
	 *          within an appropriate range (such as within a package root).
	 */
	public abstract int setPackageOfMember(int memberType, int memberId, int pkgId);
	
	/**
	 * Obtain the PackageDesc (package and scope) for the specified member. By default, members
	 * will be in the <import> package.
	 * 
	 * @param memberType 	The type of the member to query (MEMBER_TYPE_FILE, etc).
	 * @param memberId		The ID of the member (as defined in fileMgr, actionMgr, etc).
	 * @return The PackageDesc, or null if any error occurs.
	 */
	public abstract PackageDesc getPackageOfMember(int memberType, int memberId);
	
	/**
	 * Retrieve the list of members in a specific package.
	 * 
	 * @param pkgId				The package to query the members from.
	 * @param pkgScopeId		The scope to search within (SCOPE_NONE for all scopes).
	 * @param memberTypeFilter	The type of member to search for (TYPE_ANY to return all members).
	 * @return An (possibly empty) array of MemberDesc, describing the relevant package members.
	 */
	public abstract MemberDesc[] getMembersInPackage(int pkgId, int pkgScopeId, int memberTypeFilter);
	
	/**
	 * Set the (x, y) location of a package member on the package diagram.
	 * 
	 * @param memberType	The type of the member (MEMBER_TYPE_FILE, etc).
	 * @param memberId		The ID of the member (as defined in fileMgr, actionMgr, etc).
	 * @param x				The member's new X coordinate on the package diagram.
	 * @param y				The member's new Y coordinate on the package diagram.
	 * @return				ErrorCode.OK on success, ErrorCode.NOT_FOUND if the member is not found,
	 * 						or ErrorCode.OUT_OF_RANGE if the (x, y) coordinate is invalid.
	 */
	public abstract int setMemberLocation(int memberType, int memberId, int x, int y);
	
	/**
	 * Retrieve the package member's (x, y) location.
	 * @param memberType	The type of the member (MEMBER_TYPE_FILE, etc).
	 * @param memberId		The ID of the member (as defined in fileMgr, actionMgr, etc).
	 * @return				The member's (x, y) location, or null if memberType/memberId is invalid.
	 */
	public abstract MemberLocation getMemberLocation(int memberType, int memberId);

	/**
	 * Return an array of neighbours for the specified package member. A neighbour is defined
	 * as any package member that is connected to this member via a connection arrow. The order
	 * in which neighbours are returned is unspecified.
	 * 
	 * @param memberType	The type of this member (e.g. TYPE_FILE).
	 * @param memberId		The ID of this member.
	 * @param direction		NEIGHBOUR_LEFT, NEIGHBOUR_RIGHT or NEIGHBOUR_EITHER.
	 * @param showFilters	If true, return filter file groups, otherwise skip over them 
	 * @return A (possibly empty) array of MemberDesc, describing this member's connected
	 * neighbours. Returns null if any of the input parameters are invalid.
	 */
	public abstract MemberDesc[] getNeighboursOf(
			int memberType, int memberId, int direction, boolean showFilters);
	
	/**
	 * Return the set of files that are within the specified package (any scope).
	 * 
	 * @param pkgId The ID of the package we're examining.
	 * @return The set of files that reside inside that package.
	 */
	public abstract FileSet getFilesInPackage(int pkgId);

	/**
	 * Return the set of files that are within the specified package/scope.
	 * 
	 * @param pkgId The ID of the package we're examining.
	 * @param pkgScopeId The scope within the package we're interested in.
	 * @return The set of files that reside inside that package/scope.
	 */
	public abstract FileSet getFilesInPackage(int pkgId, int pkgScopeId);

	/**
	 * Return the set of files that are within the specified package/scope, given a
	 * string specification of the package/scope.
	 * 
	 * @param pkgSpec The package name, or the package/scope name.
	 * @return The FileSet of all files in this package or package/scope, or null if
	 * there's a an error in parsing the pkg/spec name.
	 */
	public abstract FileSet getFilesInPackage(String pkgSpec);

	/**
	 * Return the set of files that are outside the specified package.
	 * 
	 * @param pkgId The ID of the package we're examining.
	 * @return The set of files that reside outside that package.
	 */
	public abstract FileSet getFilesOutsidePackage(int pkgId);

	/**
	 * Return the set of files that are outside the specified package/scope.
	 * 
	 * @param pkgId The ID of the package we're examining.
	 * @param pkgScopeId The ID of the scope within the package we're interested in.
	 * @return The set of files that reside outside that package/scope.
	 */
	public abstract FileSet getFilesOutsidePackage(int pkgId, int pkgScopeId);

	/**
	 * Returns the set of files that fall outside of the package boundaries, using a string
	 * to specify the package/scope.
	 * 
	 * @param pkgSpec The package name, or the package/scope name.
	 * @return The FileSet of all files outside of this package or package/scope, or null if
	 * there's a an error in parsing the pkg/spec name.
	 */
	public abstract FileSet getFilesOutsidePackage(String pkgSpec);

	/**
	 * Return the set of actions that are within the specified package.
	 * 
	 * @param pkgId The package we're examining.
	 * @return The set of actions that reside inside that package.
	 */
	public abstract ActionSet getActionsInPackage(int pkgId);

	/**
	 * Return the set of actions that are within the specified package.
	 * 
	 * @param pkgSpec The name of the package to query.
	 * @return The set of actions that reside inside that package, null if the
	 * package name is invalid.
	 */
	public abstract ActionSet getActionsInPackage(String pkgSpec);

	/**
	 * Return the set of actions that are outside the specified package.
	 * 
	 * @param pkgId The package we're examining.
	 * @return The set of actions that reside outside that package.
	 */
	public abstract ActionSet getActionsOutsidePackage(int pkgId);

	/**
	 * Return the set of actions that are outside the specified package.
	 * 
	 * @param pkgSpec The name of the package to query.
	 * @return An array of actions that reside outside that package, null if the
	 * package name is invalid.
	 */
	public abstract ActionSet getActionsOutsidePackage(String pkgSpec);

	/**
	 * Add the specified listener to the list of objects that are notified when
	 * a package's membership changes in some way.
	 * 
	 * @param listener The object to be added as a listener.
	 */
	public void addListener(IPackageMemberMgrListener listener);

	/**
	 * Remove the specified listener from the list of objects to be notified when
	 * a package's membership changes in some way.
	 * 
	 * @param listener The object to be removed from the list of listeners.
	 */
	public void removeListener(IPackageMemberMgrListener listener);
}