1 /*

     2  * Copyright (c) 2002, 2018, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.

     8  *

     9  * This code is distributed in the hope that it will be useful, but WITHOUT

    10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    12  * version 2 for more details (a copy is included in the LICENSE file that

    13  * accompanied this code).

    14  *

    15  * You should have received a copy of the GNU General Public License version

    16  * 2 along with this work; if not, write to the Free Software Foundation,

    17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    18  *

    19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    20  * or visit www.oracle.com if you need additional information or have any

    21  * questions.

    22  */

    23 

    24 package nsk.share;

    25 

    26 import java.util.*;

    27 

    28 /**

    29  * Denotation implies a pair of algorithms for naming and

    30  * indexing of some objects.

    31  *

    32  * <p>No matter what kind of objects, just make sure that:

    33  * <ul>

    34  * <li><tt>indexFor(nameFor(index))</tt> equals to <tt>index</tt>

    35  * </li>

    36  * <li><tt>nameFor(indexFor(name))</tt> is equivalent to <tt>name</tt>

    37  * </li>

    38  * </ul>

    39  *

    40  * <p>The notions of indeces equality and names equivalence

    41  * are formalized by the methods <tt>equality()</tt> and

    42  * <tt>equivalence()</tt> correspondingly.

    43  *

    44  * <p>For better understanding of Denotation, you may want to

    45  * see the TreeNodesDenotation class as an implementation example.

    46  *

    47  * @see #equality(int[],int[])

    48  * @see #equivalence(String,String)

    49  * @see TreeNodesDenotation

    50  */

    51 abstract public class Denotation {

    52     /**

    53      * Check if the <tt>name</tt> is legal, and return the

    54      * numeric index for that object denoted by the given

    55      * <tt>name</tt>.

    56      *

    57      * @throws IllegalArgumentException If the <tt>name</tt>

    58      * is illegal.

    59      */

    60     abstract public int[] indexFor(String name);

    61 

    62     /**

    63      * Check if the <tt>index[]</tt> is legal, and return

    64      * a symbolic name for the object denoted by the given

    65      * <tt>index[]</tt>.

    66      *

    67      * @throws IllegalArgumentException If the <tt>index[]</tt>

    68      * is illegal.

    69      */

    70     abstract public String nameFor(int[] index);

    71 

    72     /**

    73      * Re-call to <tt>nameFor(int[])</tt> with the 1-element

    74      * array <tt>{i}</tt> as the <tt>index</tt> argument.

    75      *

    76      * @see #nameFor(int[])

    77      */

    78     public String nameFor(int i) {

    79         return nameFor(new int[] { i });

    80     }

    81 

    82     /**

    83      * Re-call to <tt>nameFor(int[])</tt> with the 2-elements

    84      * array <tt>{i0,i1}</tt> as the <tt>index</tt> argument.

    85      *

    86      * @see #nameFor(int[])

    87      */

    88     public String nameFor(int i0, int i1) {

    89         return nameFor(new int[] {i0, i1});

    90     }

    91 

    92     /**

    93      * Re-call to <tt>nameFor(int[])</tt> with the 3-elements

    94      * array <tt>{i0,i1,i2}</tt> as the <tt>index</tt> argument.

    95      *

    96      * @see #nameFor(int[])

    97      */

    98     public String nameFor(int i0, int i1, int i2) {

    99         return nameFor(new int[] {i0, i1, i2});

   100     }

   101 

   102     /**

   103      * Indeces equality means equality of objects they denote.

   104      *

   105      * <p>Indeces <tt>index1[]</tt> and <tt>index2[]</tt> are

   106      * equal, if they are equal as <tt>int[]</tt> arrays. But,

   107      * there is no index equal to <tt>null</tt>; particularly,

   108      * <tt>null</tt> is not equal to itself.

   109      *

   110      * @see Arrays#equals(int[],int[])

   111      */

   112     public boolean equality(int[] index1, int[] index2) {

   113         if (index1 == null || index2 == null)

   114             return false;

   115         return Arrays.equals(index1,index2);

   116     }

   117 

   118     /**

   119      * Names equivalence means equality of objects they denote.

   120      *

   121      * <p>Strings <tt>name1</tt> and <tt>name2</tt> are equivalent,

   122      * if correspondent indeces are equal. There is no <tt>name</tt>

   123      * equivalent to <tt>null</tt>; particularly, <tt>null</tt> is

   124      * not equivalent to itself.

   125      *

   126      * @see #equality(int[],int[])

   127      */

   128     public boolean equivalence(String name1, String name2) {

   129         if (name1 == null || name2 == null)

   130             return false;

   131         return equality(indexFor(name1),indexFor(name2));

   132     }

   133 

   134     /**

   135      * Dummy constructor.

   136      */

   137     protected Denotation() {

   138     }

   139 }