1 /*

     2  * Copyright (c) 2003, 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.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

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

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

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

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

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

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

    23  * questions.

    24  */

    25 

    26 package jdk.internal.misc;

    27 

    28 import java.lang.annotation.Annotation;

    29 import java.lang.module.ModuleDescriptor;

    30 import java.lang.reflect.Executable;

    31 import java.lang.reflect.Method;

    32 import java.net.URI;

    33 import java.nio.charset.CharacterCodingException;

    34 import java.nio.charset.Charset;

    35 import java.security.AccessControlContext;

    36 import java.security.ProtectionDomain;

    37 import java.util.Iterator;

    38 import java.util.List;

    39 import java.util.Map;

    40 import java.util.concurrent.ConcurrentHashMap;

    41 import java.util.stream.Stream;

    42 

    43 import jdk.internal.module.ServicesCatalog;

    44 import jdk.internal.reflect.ConstantPool;

    45 import sun.reflect.annotation.AnnotationType;

    46 import sun.nio.ch.Interruptible;

    47 

    48 public interface JavaLangAccess {

    49 

    50     /**

    51      * Returns the list of {@code Method} objects for the declared public

    52      * methods of this class or interface that have the specified method name

    53      * and parameter types.

    54      */

    55     List<Method> getDeclaredPublicMethods(Class<?> klass, String name, Class<?>... parameterTypes);

    56 

    57     /**

    58      * Return the constant pool for a class.

    59      */

    60     ConstantPool getConstantPool(Class<?> klass);

    61 

    62     /**

    63      * Compare-And-Set the AnnotationType instance corresponding to this class.

    64      * (This method only applies to annotation types.)

    65      */

    66     boolean casAnnotationType(Class<?> klass, AnnotationType oldType, AnnotationType newType);

    67 

    68     /**

    69      * Get the AnnotationType instance corresponding to this class.

    70      * (This method only applies to annotation types.)

    71      */

    72     AnnotationType getAnnotationType(Class<?> klass);

    73 

    74     /**

    75      * Get the declared annotations for a given class, indexed by their types.

    76      */

    77     Map<Class<? extends Annotation>, Annotation> getDeclaredAnnotationMap(Class<?> klass);

    78 

    79     /**

    80      * Get the array of bytes that is the class-file representation

    81      * of this Class' annotations.

    82      */

    83     byte[] getRawClassAnnotations(Class<?> klass);

    84 

    85     /**

    86      * Get the array of bytes that is the class-file representation

    87      * of this Class' type annotations.

    88      */

    89     byte[] getRawClassTypeAnnotations(Class<?> klass);

    90 

    91     /**

    92      * Get the array of bytes that is the class-file representation

    93      * of this Executable's type annotations.

    94      */

    95     byte[] getRawExecutableTypeAnnotations(Executable executable);

    96 

    97     /**

    98      * Returns the elements of an enum class or null if the

    99      * Class object does not represent an enum type;

   100      * the result is uncloned, cached, and shared by all callers.

   101      */

   102     <E extends Enum<E>> E[] getEnumConstantsShared(Class<E> klass);

   103 

   104     /**

   105      * Set current thread's blocker field.

   106      */

   107     void blockedOn(Interruptible b);

   108 

   109     /**

   110      * Registers a shutdown hook.

   111      *

   112      * It is expected that this method with registerShutdownInProgress=true

   113      * is only used to register DeleteOnExitHook since the first file

   114      * may be added to the delete on exit list by the application shutdown

   115      * hooks.

   116      *

   117      * @param slot  the slot in the shutdown hook array, whose element

   118      *              will be invoked in order during shutdown

   119      * @param registerShutdownInProgress true to allow the hook

   120      *        to be registered even if the shutdown is in progress.

   121      * @param hook  the hook to be registered

   122      *

   123      * @throws IllegalStateException if shutdown is in progress and

   124      *         the slot is not valid to register.

   125      */

   126     void registerShutdownHook(int slot, boolean registerShutdownInProgress, Runnable hook);

   127 

   128     /**

   129      * Returns a new Thread with the given Runnable and an

   130      * inherited AccessControlContext.

   131      */

   132     Thread newThreadWithAcc(Runnable target, AccessControlContext acc);

   133 

   134     /**

   135      * Invokes the finalize method of the given object.

   136      */

   137     void invokeFinalize(Object o) throws Throwable;

   138 

   139     /**

   140      * Returns the ConcurrentHashMap used as a storage for ClassLoaderValue(s)

   141      * associated with the given class loader, creating it if it doesn't already exist.

   142      */

   143     ConcurrentHashMap<?, ?> createOrGetClassLoaderValueMap(ClassLoader cl);

   144 

   145     /**

   146      * Defines a class with the given name to a class loader.

   147      */

   148     Class<?> defineClass(ClassLoader cl, String name, byte[] b, ProtectionDomain pd, String source);

   149 

   150     /**

   151      * Returns a class loaded by the bootstrap class loader.

   152      */

   153     Class<?> findBootstrapClassOrNull(ClassLoader cl, String name);

   154 

   155     /**

   156      * Define a Package of the given name and module by the given class loader.

   157      */

   158     Package definePackage(ClassLoader cl, String name, Module module);

   159 

   160     /**

   161      * Invokes Long.fastUUID

   162      */

   163     String fastUUID(long lsb, long msb);

   164 

   165     /**

   166      * Record the non-exported packages of the modules in the given layer

   167      */

   168     void addNonExportedPackages(ModuleLayer layer);

   169 

   170     /**

   171      * Invalidate package access cache

   172      */

   173     void invalidatePackageAccessCache();

   174 

   175     /**

   176      * Defines a new module to the Java virtual machine. The module

   177      * is defined to the given class loader.

   178      *

   179      * The URI is for information purposes only, it can be {@code null}.

   180      */

   181     Module defineModule(ClassLoader loader, ModuleDescriptor descriptor, URI uri);

   182 

   183     /**

   184      * Defines the unnamed module for the given class loader.

   185      */

   186     Module defineUnnamedModule(ClassLoader loader);

   187 

   188     /**

   189      * Updates the readability so that module m1 reads m2. The new read edge

   190      * does not result in a strong reference to m2 (m2 can be GC'ed).

   191      *

   192      * This method is the same as m1.addReads(m2) but without a permission check.

   193      */

   194     void addReads(Module m1, Module m2);

   195 

   196     /**

   197      * Updates module m to read all unnamed modules.

   198      */

   199     void addReadsAllUnnamed(Module m);

   200 

   201     /**

   202      * Updates module m1 to export a package to module m2. The export does

   203      * not result in a strong reference to m2 (m2 can be GC'ed).

   204      */

   205     void addExports(Module m1, String pkg, Module m2);

   206 

   207     /**

   208      * Updates a module m to export a package to all unnamed modules.

   209      */

   210     void addExportsToAllUnnamed(Module m, String pkg);

   211 

   212     /**

   213      * Updates module m1 to open a package to module m2. Opening the

   214      * package does not result in a strong reference to m2 (m2 can be GC'ed).

   215      */

   216     void addOpens(Module m1, String pkg, Module m2);

   217 

   218     /**

   219      * Updates module m to open a package to all unnamed modules.

   220      */

   221     void addOpensToAllUnnamed(Module m, String pkg);

   222 

   223     /**

   224      * Updates module m to open all packages returned by the given iterator.

   225      */

   226     void addOpensToAllUnnamed(Module m, Iterator<String> packages);

   227 

   228     /**

   229      * Updates module m to use a service.

   230      */

   231     void addUses(Module m, Class<?> service);

   232 

   233     /**

   234      * Returns true if module m reflectively exports a package to other

   235      */

   236     boolean isReflectivelyExported(Module module, String pn, Module other);

   237 

   238     /**

   239      * Returns true if module m reflectively opens a package to other

   240      */

   241     boolean isReflectivelyOpened(Module module, String pn, Module other);

   242 

   243     /**

   244      * Returns the ServicesCatalog for the given Layer.

   245      */

   246     ServicesCatalog getServicesCatalog(ModuleLayer layer);

   247 

   248     /**

   249      * Returns an ordered stream of layers. The first element is the

   250      * given layer, the remaining elements are its parents, in DFS order.

   251      */

   252     Stream<ModuleLayer> layers(ModuleLayer layer);

   253 

   254     /**

   255      * Returns a stream of the layers that have modules defined to the

   256      * given class loader.

   257      */

   258     Stream<ModuleLayer> layers(ClassLoader loader);

   259 

   260     /**

   261      * Constructs a new {@code String} by decoding the specified subarray of

   262      * bytes using the specified {@linkplain java.nio.charset.Charset charset}.

   263      *

   264      * The caller of this method shall relinquish and transfer the ownership of

   265      * the byte array to the callee since the later will not make a copy.

   266      *

   267      * @param bytes the byte array source

   268      * @param cs the Charset

   269      * @return the newly created string

   270      * @throws CharacterCodingException for malformed or unmappable bytes

   271      */

   272     String newStringNoRepl(byte[] bytes, Charset cs) throws CharacterCodingException;

   273 

   274     /**

   275      * Encode the given string into a sequence of bytes using the specified Charset.

   276      *

   277      * This method avoids copying the String's internal representation if the input

   278      * is ASCII.

   279      *

   280      * This method throws CharacterCodingException instead of replacing when

   281      * malformed input or unmappable characters are encountered.

   282      *

   283      * @param s the string to encode

   284      * @param cs the charset

   285      * @return the encoded bytes

   286      * @throws CharacterCodingException for malformed input or unmappable characters

   287      */

   288     byte[] getBytesNoRepl(String s, Charset cs) throws CharacterCodingException;

   289 

   290     /**

   291      * Returns a new string by decoding from the given utf8 bytes array.

   292      *

   293      * @param off the index of the first byte to decode

   294      * @param len the number of bytes to decode

   295      * @return the newly created string

   296      * @throws IllegalArgumentException for malformed or unmappable bytes.

   297      */

   298     String newStringUTF8NoRepl(byte[] bytes, int off, int len);

   299 

   300     /**

   301      * Encode the given string into a sequence of bytes using utf8.

   302      *

   303      * @param s the string to encode

   304      * @return the encoded bytes in utf8

   305      * @throws IllegalArgumentException for malformed surrogates

   306      */

   307     byte[] getBytesUTF8NoRepl(String s);

   308 

   309     /**

   310      * Set the cause of Throwable

   311      * @param cause set t's cause to new value

   312      */

   313     void setCause(Throwable t, Throwable cause);

   314 }