View source for OTEquinox/Aspect Binding Negotiation

{{important|Change of namespace|In versions upto 1.4.0 (served from <code>www.objectteams.org</code>) the IDs of OT/Equionx extension points start with <code>org.objectteams</code>.<br>
During the project move to Eclipse.org this has been renamed to <code>org.eclipse.objectteams...</code>.}}

==Introduction==
Roles in OT/Equinox may have specific privileges regarding their base classes, which allows them to by-pass standard visibility rules. Aspect binding negotiation is a concept by which any desired level of security can be achieved on top of the mechanisms of decapsulation.

:'''Two kinds of aspect permissions are distinguished:'''
# The permission to define an [[OTEquinox/Aspect Binding|Aspect Binding]] to a given base bundle 
# The permission to apply [[OTEquinox/Forced Export|Forced Exports]] to a given package of a base bundle 

:'''Aspect permissions can be configured at these levels:'''
# Granting of forced exports by entries in [[OTEquinox/Config Ini|config.ini]] which apply to a given Eclipse '''installation''' (all users, all workspaces) 
# General '''workspace''' configuration defines the defaults that apply to aspect bindings and forced exports respectively, in case no other statement is made. 
# Specific '''workspace''' configuration can be used to grant or deny individual aspect bindings and or forced exports. 
# Participants in a '''negotation''' protocol dynamically vote which aspect permissions should be granted at runtime. 
 

Aspect permissions are combined in a three-valued logic of DENY, GRANT, UNDEFINED, where DENY has highest priority, UNDEFINED lowest. This means a single DENY suffices to strictly disallow a requested aspect binding (or forced export). In order to grant an aspect permission, at least one GRANT vote must be given. 

==Installation-wide configuration==
For this level of configuration please see [[OTEquinox/Forced Export|Forced Exports]]. 

==General workspace configuration==
A simple textfile in the workspace defines the defaults for aspect permissions. It is located in
<pre><workspace>/.metadata/.plugins/org.objectteams.otequinox/negotiationDefaults.txt</pre>

At the first use of a workspace this file is initialized with the following content: 
<pre>aspect.binding.default=GRANT
forced.export.default=UNDEFINED</pre>

Manually changing the second line to <code>forced.export.default=GRANT</code>, e.g., would effectively grant all forced-exports request. 

==Specific workspace configuration==
OT/Equinox may store specific permissions for specific requests in the workspace. The format of this is, however, subject to future changes. Currently, two files <code>grantedForcedExports.txt</code> and <code>deniedForcedExports.txt</code> are used internally, which use a syntax similar to what is used in [[OTEquinox/Forced Export|Forced Exports]].

==Dynamic Negotiation==
OT/Equinox provides the extension point 
<pre>org.objectteams.otequinox.aspectBindingNegotiators</pre>

* See also the [http://www.objectteams.org/distrib/documentation/pde_schema_org-objectteams-otequinox-aspectBindingNegotiators.html extension point documentation]. 


Extensions to be registered at this extension point must implement the following interface: 
<source lang="java">
public interface IAspectRequestNegotiator {
        
        /** 
         * Check whether a request for forced exports should be granted.
         * @param aspectBundleSymbolicName the aspect issuing the request
         * @param baseBundleSymbolicName   the affected base bundle
         * @param basePackage              the affected base package
         * @param previousNegotiation      the result of negotations up-to this point
         * @return a structure holding the answer, must not be null.
         */
        AspectBindingRequestAnswer checkForcedExport(String aspectBundleSymbolicName, String baseBundleSymbolicName, String basePackage, AspectPermission previousNegotiation);

        /** 
         * Check whether a request for an aspect binding should be granted.
         * @param aspectBundleSymbolicName the aspect issuing the request
         * @param baseBundleSymbolicName   the affected base bundle
         * @param teamClass                an affecting team class involved in this aspect binding
         * @param previousNegotiation      the result of negotations up-to this point
         * @return a structure holding the answer, must not be null.
         */
        AspectBindingRequestAnswer checkAspectBinding(String aspectBundleSymbolicName, String baseBundleSymbolicName, String teamClass, AspectPermission previousNegotiation);
}</source>

where an AspectBindingRequestAnswer is defined by 

<source lang="java">public class AspectBindingRequestAnswer 
{
        /** Should this answer be remembered persistently? */
        public boolean persistent;
        /** Should this answer be applied to all subsequent requests? */
        public boolean allRequests;
        /** The actual answer. */
        public AspectPermission permission;
}
public enum AspectPermission {
        /** Not influencing negotiation between other parties. */
        UNDEFINED,
        /** A permission is granted unless someone else denies it. */
        GRANT, 
        /** A permission is explicitly denied. Cannot be overridden. */
        DENY;
}</source>

Whenever the OT/Equinox runtime encounters an aspect binding or the request for a forced exports it iterates all registered negotiators until either a DENY has been received or all negotiators have cast their vote. 
By setting the <code>persistent</code> flag to true, a negotiator tells the runtime to store this particular vote. 


==Example: org.objectteams.otequinox.aspectasker==
{{warning|Needs update|The plugin described here is currently not maintained due to pending issues observed on MacOS}}
An example plugin is provided that interactively asks the user to vote GRANT, DENY or pass unchanged (UNDEFINED). This demonstrates how the extension point can be used to give the control to the end user, who will have to deny or grant each single request at least once.
 
Other plugins can contribute to this negotation using other strategies. Even cryptographic protocols which involve checking of specific certificates etc. can easily be plugged into the OT/Equinox runtime. 

==References==
* This extension point has been requested and discussed in [http://trac.objectteams.org/ot/ticket/199 ticket #199].
* <strike>The optional aspectasker plugin and feature is available from the update site in category "Object Teams Contributions"</strike> (''currently unavailable'')
* Generated documentation: [http://www.objectteams.org/distrib/documentation/pde_schema_org-objectteams-otequinox-aspectBindingNegotiators.html org.objectteams.otequinox.aspectBindingNegotiators].

[[Category:OTEquinox]]