/ elib / legacy

API Legend

Adapted from Announcing E 0.8.20t: A preview of a real 0.8.20:

The new javadoc-umentation is now posted here, and represents real progress towards edoc. This documentation includes all the public interface of Java code available to the ELib programmer, both from the E implementation itself, and for each java or SWT package which contains any tamed class. Besides the normal javadoc info, these pages also reflect the taming of the API. (I should be able to include doc-comments extracted from E code soon, but not quite yet.)

Each class or interface is annotated with an initial bold italic color-coded:

• "Safe:" -- if the class is importable via the import__uriGetter, ie, by an expression of the form <import:...> A class should only be declared Safe when it's enabled (see below) constructors and static members provide no ability to effect or be effected by the world outside the invoking object (ie, provide no "authority" as we define the term). If you see any questionable Safe declarations, please ask. Our security rests on not making errors of inclusion here. Note: the AWT and Swing classes currently declared Safe will be reclassified into a new category, since we don't ever expect to completely tame these.

• "Unsafe:" -- if the class is importable via the unsafe__uriGetter, ie, by an expression of the form <unsafe:...> A class should only be declared Unsafe when there's a clear theory of the authority provided by its enabled constructors and static members, and when these have been tamed in accordance with this theory.

• "Untamed:" -- if this class has not been tamed. Currently, such classes are still importable via <unsafe:...>, but this will eventually be controlled by a properties setting, with the default being for untamed classes to be unimportable. However, we can't make this change until we make it much easier to tame existing classes.

Each member (method, constructor, or field) is annotated with an initial:

• "Enabled:" -- if this member is visible both to Java clients and to E/ELib clients. A member should only be enabled if it follows capability discipline. For a constructor or static member, this means it provides no more authority than is thought to be provided by the imported class (the class' maker). For an instance member, this means it provides no more authority than is thought to be provided by an instance.

• "Suppressed:" -- if the member is not visible to the E-language programmer, nor to the ELib programmer via the ELib invocation mechanisms (E.call(...), E.send(...), etc). These are still accessible to the Java programmer, and therefore to the ELib programmer when using Java's "." operator.

• "Added:" -- if the member is directly visible to the E/ELib programmer as if it were a member of the class, though it's actually a static public member of a sugaring class. The Java programmer must invoke these indirectly by calling the static member instead. For example using Component.transferFocus(Component[], Component) the E-language programmer can say

  def makeComponent := <import:java.awt.Component>
  makeComponent.transferFocus(oldComponents, newComponent)

  whereas the Java programmer would say

  import org.erights.e.meta.java.awt.ComponentMakerSugar;
  ComponentMakerSugar.transferFocus(oldComponents, newComponent);

  For an added instance method, like Component.iterate(AssocFunc) the Java programmer would provide the receiver as first argument to the static method:

  import org.erights.e.meta.java.awt.ComponentSugar;
  ComponentSugar.iterate(component, assocFunc);