| |
| This directory contains an example ANTLR grammar for a little |
| language called OGNL (pronounced OGG-null), which stands for |
| Object-Graph Navigation Language. OGNL is an expression language for |
| setting and getting properties of Java objects, and can be used as is |
| or as a starting point for other projects. |
| |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| * * |
| * Copyright (c) 2002, Drew Davidson and Luke Blanshard * |
| * All rights reserved. * |
| * * |
| * Redistribution and use in source and binary forms, with or without * |
| * modification, are permitted provided that the following conditions are * |
| * met: * |
| * * |
| * Redistributions of source code must retain the above copyright notice, * |
| * this list of conditions and the following disclaimer. * |
| * Redistributions in binary form must reproduce the above copyright * |
| * notice, this list of conditions and the following disclaimer in the * |
| * documentation and/or other materials provided with the distribution. * |
| * Neither the name of the Drew Davidson nor the names of its contributors * |
| * may be used to endorse or promote products derived from this software * |
| * without specific prior written permission. * |
| * * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * |
| * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * |
| * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * |
| * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * |
| * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, * |
| * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, * |
| * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS * |
| * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * |
| * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * |
| * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF * |
| * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH * |
| * DAMAGE. * |
| * * |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| |
| 1. Overview |
| =========== |
| |
| As a tool and a code base, OGNL can be used as is or can be |
| cannibalized for its parts. Its possible uses and features include: |
| |
| * OGNL was first conceived as a mechanism for associating parts of |
| GUIs with model objects. A single expression is used both to pull |
| the appropriate value from the model for display by a widget, and |
| to push the newly edited value back into the model when editing is |
| complete. |
| |
| * OGNL's current syntax includes most of Java's operators and a few |
| of its own. It is probably close to powerful enough to be used by |
| a debugger or other system that requires run-time interpretation |
| of expressions. |
| |
| * OGNL has fully integrated support for arbitrary-precision math, as |
| embodied by the classes of the java.math package, meaning that |
| OGNL's arithmetic operators work on BigIntegers and BigDecimals as |
| well as the primitive types. While this is of marginal use (at |
| best) to OGNL as a GUI hooker-upper, it could be valuable in other |
| settings. |
| |
| |
| 2. Building |
| =========== |
| |
| OGNL was designed for JDK 1.2 (now known as Java 2). It is possible |
| to modify the code to run under 1.1, though the extensive use of the |
| 1.2 collections API makes this a bit painful. If you have the JDK 1.1 |
| version of the 1.2 collections, which was made available in the summer |
| of 1998 by the InfoBus group at Sun (and still available in June 1999 |
| at http://java.sun.com/beans/infobus), the job will be easier. |
| |
| If you have GNU make, the GNUmakefile provided will build the OGNL |
| package, run the test program, and use javadoc to produce API |
| documentation; all on NT, Win98 or Unix systems. Please see that |
| file for more information on what build targets are available. |
| |
| |
| 3. Documentation |
| ================ |
| |
| OGNL is documented in the accompanying file "package.html", which is |
| used by javadoc as the ognl package description. The best way to view |
| this is to generate javadoc (using "make doc" if you have GNU make), |
| and then open the generated file "index.html" in the javadoc-created |
| "doc" subdirectory, using your favorite HTML browser. The package |
| description will be below the lists of interfaces and classes. |
| |
| The accompanying test program, Test.java, can be thought of as |
| "practical documentation." |
| |
| |
| 4. Feedback |
| =========== |
| |
| If you have any observations or complaints about OGNL or its |
| implementation or documentation, we would like to hear from you. You |
| can reach Luke Blanshard by email at luke@quiq.com, or Drew Davidson at |
| drew@ognl.org. |