package ca.ubc.cs.spl.aspectPatterns.patternLibrary;

/* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This file is part of the design patterns project at UBC
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * either https://www.mozilla.org/MPL/ or https://aspectj.org/MPL/.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ca.ubc.cs.spl.aspectPatterns.
 *
 * For more details and the latest version of this code, please see:
 * https://www.cs.ubc.ca/labs/spl/projects/aodps.html
 *
 * Contributor(s):
 */

import org.aspectj.lang.JoinPoint;

/**
 * Defines the abstracted Proxy design pattern.<p>
 *
 * Concrete sub-aspects define the following: <UL>
 *  <LI> Which class(es) are <i>RealSubject</i>s
 *  <LI> Which requests need to be handled by the <i>Proxy</i>
 *       (methods, field accesses)
 *  <LI> What to return in case of a proxy-covered
 *       access to a method.
 * </UL>
 *
 * @author  Jan Hannemann
 * @author  Gregor Kiczales
 * @version 1.1, 02/17/04
 */

public abstract aspect ProxyProtocol {

    /**
     * Defines the Subject role (used for correct typing)
     */

    protected interface Subject {}

    /**
     * Captures all accesses to the subject that should be covered by
     * this pattern instance.
     */

	protected abstract pointcut requests();

	/**
	 * Extends the <code>requests()</code> pointcut to include a
	 * field for the joinpoint. Used internally only.
	 */

	private pointcut requestsByCaller(Object caller):
	    requests() && this(caller);

    /**
     * Intercepts accesses to protected parts of the OutputSubject.
     * If access is proxy protected, the method
     * <code>handleProxyProtection(..)</code> is called instead.
     *
     * @param caller the object responsible for the protected access
     * @param subject the subject receiving the call
     */

	Object around(Object caller, Subject subject):
	    requestsByCaller(caller) && target(subject) {

		if (! isProxyProtected(caller, subject, thisJoinPoint) )
			return proceed(caller, subject);
		return handleProxyProtection(caller, subject, thisJoinPoint);
	}

	/**
	 * Checks whether the request should be handled by the Proxy or not
	 *
     * @param caller the object responsible for the protected access
     * @param subject the subject receiving the call
     * @param joinPoint the joinpoint associated with the protected access
     *
     * @return true if the access is covered by the proxy, false otherwise
     */

	protected abstract boolean isProxyProtected(Object caller,
	                                     Subject subject,
	                                     JoinPoint joinPoint);

	/**
	 * For delegation: Provides an alternative return value if access
	 * is proxy protected. A default implementation is supplied so that
	 * concrete subaspects are not forced to implement the method.
	 *
     * @param caller the object responsible for the proxy protected access
     * @param subject the subject receiving the call
     * @param joinPoint the joinpoint associated with the proxy protected
     * access
     *
     * @return an alternative return value
     */

	protected Object handleProxyProtection(Object caller,
	                                       Subject subject,
	                                       JoinPoint joinPoint) {
		return null;
	}
}