src/jdk.dynalink/share/classes/jdk/dynalink/package-info.java

*** 80,125 ****
         OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
         ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
  
  /**
!  * <p>
!  * Dynalink is a library for dynamic linking of high-level operations on objects.
!  * These operations include "read a property",
!  * "write a property", "invoke a function" and so on. Dynalink is primarily
!  * useful for implementing programming languages where at least some expressions
!  * have dynamic types (that is, types that can not be decided statically), and
!  * the operations on dynamic types are expressed as
!  * {@link java.lang.invoke.CallSite call sites}. These call sites will be
!  * linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}
!  * at run time based on actual types of the values the expressions evaluated to.
!  * These can change between invocations, necessitating relinking the call site
!  * multiple times to accommodate new types; Dynalink handles all that and more.
!  * <p>
!  * Dynalink supports implementation of programming languages with object models
!  * that differ (even radically) from the JVM's class-based model and have their
!  * custom type conversions.
!  * <p>
!  * Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
!  * package.
!  * <p>
!  *
!  * While {@link java.lang.invoke} provides a low level API for dynamic linking
!  * of {@code invokedynamic} call sites, it does not provide a way to express
!  * higher level operations on objects, nor methods that implement them. These
!  * operations are the usual ones in object-oriented environments: property
!  * access, access of elements of collections, invocation of methods and
!  * constructors (potentially with multiple dispatch, e.g. link- and run-time
!  * equivalents of Java overloaded method resolution). These are all functions
!  * that are normally desired in a language on the JVM. If a language is
!  * statically typed and its type system matches that of the JVM, it can
!  * accomplish this with use of the usual invocation, field access, etc.
!  * instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the
!  * language is dynamic (hence, types of some expressions are not known until
!  * evaluated at run time), or its object model or type system don't match
!  * closely that of the JVM, then it should use {@code invokedynamic} call sites
!  * instead and let Dynalink manage them.
   * <h2>Example</h2>
   * Dynalink is probably best explained by an example showing its use. Let's
   * suppose you have a program in a language where you don't have to declare the
   * type of an object and you want to access a property on it:
   * <pre>
--- 80,91 ----
         OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
         ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
  
  /**
!  * Contains interfaces and classes that are used to link an {@code invokedynamic} call site.
!  *
   * <h2>Example</h2>
   * Dynalink is probably best explained by an example showing its use. Let's
   * suppose you have a program in a language where you don't have to declare the
   * type of an object and you want to access a property on it:
   * <pre>