modules/cldc-compact/src/main/java/cc/squirreljme/jvm/mle/JarPackageShelf.java

   1 // -*- Mode: Java; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // ---------------------------------------------------------------------------
   9
  10 package cc.squirreljme.jvm.mle;
  11
  12 import cc.squirreljme.jvm.mle.brackets.JarPackageBracket;
  13 import cc.squirreljme.jvm.mle.exceptions.MLECallError;
  14 import cc.squirreljme.runtime.cldc.annotation.Api;
  15 import cc.squirreljme.runtime.cldc.annotation.SquirrelJMEVendorApi;
  16 import java.io.InputStream;
  17 import org.jetbrains.annotations.CheckReturnValue;
  18 import org.jetbrains.annotations.Contract;
  19 import org.jetbrains.annotations.NotNull;
  20 import org.jetbrains.annotations.Nullable;
  21 import org.jetbrains.annotations.Range;
  22
  23 /**
  24  * This allows access to the library class path and resources.
  25  *
  26  * @since 2020/06/07
  27  */
  28 @SuppressWarnings("UnstableApiUsage")
  29 @SquirrelJMEVendorApi
  30 public final class JarPackageShelf
  31 {
  32         /**
  33          * Returns the classpath of the current program.
  34          *
  35          * @return The classpath of the current program.
  36          * @since 2020/06/07
  37          */
  38         @SquirrelJMEVendorApi
  39         public static native JarPackageBracket[] classPath();
  40
  41         /**
  42          * Checks if the given brackets refer to the same JAR.
  43          *
  44          * @param __a The first JAR.
  45          * @param __b The second JAR.
  46          * @return If these are equal or not.
  47          * @throws MLECallError If either argument is {@code null}.
  48          * @since 2020/07/02
  49          */
  50         @SquirrelJMEVendorApi
  51         public static native boolean equals(
  52                 JarPackageBracket __a, JarPackageBracket __b)
  53                 throws MLECallError;
  54
  55         /**
  56          * Returns the libraries which are available to the virtual machine.
  57          *
  58          * @return The libraries that are currently available.
  59          * @since 2020/10/31
  60          */
  61         @SquirrelJMEVendorApi
  62         public static native JarPackageBracket[] libraries();
  63
  64         /**
  65          * Returns the ID of the specific library.
  66          *
  67          * @param __jar The Jar to get the library ID of.
  68          * @return The library ID for the given Jar.
  69          * @throws MLECallError If the library is not valid.
  70          * @since 2023/12/18
  71          */
  72         @SquirrelJMEVendorApi
  73         public static native int libraryId(@NotNull JarPackageBracket __jar)
  74                 throws MLECallError;
  75
  76         /**
  77          * Returns the path to the given JAR.
  78          *
  79          * Note that this may or may not be a physical path, it could be a
  80          * representation of the JAR file in string form.
  81          *
  82          * @param __jar The JAR to get the path of.
  83          * @return The path of the given JAR.
  84          * @throws MLECallError If the JAR is not valid.
  85          * @since 2020/10/31
  86          */
  87         @SquirrelJMEVendorApi
  88         public static native String libraryPath(@NotNull JarPackageBracket __jar)
  89                 throws MLECallError;
  90
  91         /**
  92          * Opens the resource from the input stream.
  93          *
  94          * @param __jar The JAR to open.
  95          * @param __rc The resource to load from the given JAR.
  96          * @return Input stream to the resource, may be {@code null} if it does
  97          * not exist.
  98          * @throws MLECallError If the JAR is not valid or the resource was not
  99          * specified.
 100          * @since 2020/06/07
 101          */
 102         @SquirrelJMEVendorApi
 103         @Nullable
 104         public static native InputStream openResource(
 105                 @NotNull JarPackageBracket __jar,
 106                 @NotNull String __rc)
 107                 throws MLECallError;
 108
 109         /**
 110          * Returns the prefix code for the class.
 111          *
 112          * @param __jar The Jar to get the prefix code from.
 113          * @return The prefix code in the JAR, mapped accordingly to 37 radix,
 114          * will return -1 if there is none.
 115          * @throws MLECallError If {@code __jar} is null.
 116          * @since 2023/07/19
 117          */
 118         @SquirrelJMEVendorApi
 119         @Range(from = -1, to = 1296)
 120         public static native int prefixCode(@NotNull JarPackageBracket __jar)
 121                 throws MLECallError;
 122
 123         /**
 124          * Reads a section of a JAR representation, note that the format is not
 125          * necessarily in the format of a JAR or ZIP file but may exist in SQC
 126          * form.
 127          *
 128          * @param __jar The library to read the raw data from.
 129          * @param __jarOffset The offset into the raw data.
 130          * @param __b The buffer to write into.
 131          * @param __o The offset into the buffer.
 132          * @param __l The length of the buffer.
 133          * @return The number of bytes read from the raw Jar data.
 134          * @throws MLECallError On null arguments or if the offset and/or length
 135          * exceed the array bounds.
 136          * @since 2022/03/04
 137          */
 138         @SquirrelJMEVendorApi
 139         @CheckReturnValue
 140         public static native int rawData(@NotNull JarPackageBracket __jar,
 141                 @Range(from = 0, to = Integer.MAX_VALUE) int __jarOffset,
 142                 @NotNull byte[] __b,
 143                 @Range(from = 0, to = Integer.MAX_VALUE) int __o,
 144                 @Range(from = 0, to = Integer.MAX_VALUE) int __l)
 145                 throws MLECallError;
 146
 147         /**
 148          * Returns the raw size of a given JAR, note that this may not be
 149          * the size of a JAR file but a compiled form such a SQC.
 150          *
 151          * @param __jar The JAR to lookup.
 152          * @return The raw size of the JAR, this will be a negative value if the
 153          * JAR is virtual and its size is not known.
 154          * @throws MLECallError If {@code __jar} is null.
 155          * @since 2022/03/04
 156          */
 157         @SquirrelJMEVendorApi
 158         @CheckReturnValue
 159         public static native int rawSize(@NotNull JarPackageBracket __jar)
 160                 throws MLECallError;
 161 }