Package io.microsphere.util.jar

Class JarUtils

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String MANIFEST_RESOURCE_PATH
      The resource path of Manifest file in JAR archive.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      protected static void assertJarURLProtocol​(java.net.URL jarURL)
      Assert jarURL argument is valid , only supported protocols : jar and file
      protected static void doExtract​(java.util.jar.JarFile jarFile, java.lang.Iterable<java.util.jar.JarEntry> jarEntries, java.io.File targetDirectory)  
      protected static java.util.List<java.util.jar.JarEntry> doFilter​(java.lang.Iterable<java.util.jar.JarEntry> jarEntries, JarEntryFilter jarEntryFilter)  
      static void extract​(java.io.File jarSourceFile, java.io.File targetDirectory)
      Extracts the contents of the specified JAR file to the given target directory.
      static void extract​(java.io.File jarSourceFile, java.io.File targetDirectory, JarEntryFilter jarEntryFilter)
      Extracts the contents of the specified JAR file to the given target directory, optionally filtering entries.
      static void extract​(java.net.URL jarResourceURL, java.io.File targetDirectory, JarEntryFilter jarEntryFilter)
      Extracts entries from a JAR resource pointed by the given URL to the specified target directory, optionally filtering which entries to extract.
      static void extract​(java.util.jar.JarFile jarFile, java.io.File targetDirectory, JarEntryFilter jarEntryFilter)
      Extracts entries from a JAR file to the specified target directory, optionally filtering which entries to extract.
      static java.util.List<java.util.jar.JarEntry> filter​(java.util.jar.JarFile jarFile, JarEntryFilter jarEntryFilter)
      Filters the entries of a JAR file based on the provided JarEntryFilter.
      static java.util.jar.JarEntry findJarEntry​(java.net.URL jarURL)
      Finds and returns the JarEntry from the specified JAR URL.
      static java.lang.String resolveJarAbsolutePath​(java.net.URL jarURL)
      Resolves the absolute path of the JAR file from the provided URL.
      static java.lang.String resolveRelativePath​(java.net.URL jarURL)
      Resolves the relative path from the given JAR URL.
      static java.util.jar.JarFile toJarFile​(java.net.URL jarURL)
      Creates a JarFile from the specified URL.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • MANIFEST_RESOURCE_PATH

        public static final java.lang.String MANIFEST_RESOURCE_PATH
        The resource path of Manifest file in JAR archive. Typically located under META-INF/MANIFEST.MF in standard Java archives.
        See Also:
        Constant Field Values

    • Method Detail

      • toJarFile

        @Nullable
public static java.util.jar.JarFile toJarFile​(java.net.URL jarURL)
                                       throws java.io.IOException
        Creates a JarFile from the specified URL.

        This method resolves the absolute path of the JAR file from the provided URL and constructs a new JarFile instance. If the URL does not point to a valid JAR or file resource, this method returns null.

        Example Usage

        
 URL jarURL = new URL("jar:file:/path/to/file.jar!/entry");
 JarFile jarFile = JarUtils.toJarFile(jarURL);
        Parameters:
        jarURL - the URL pointing to a JAR file or entry; must not be null
        Returns:
        a new JarFile instance if resolved successfully, or null if resolution fails
        Throws:
        java.io.IOException - if an I/O error occurs while creating the JAR file

      • assertJarURLProtocol

        protected static void assertJarURLProtocol​(java.net.URL jarURL)
                                    throws java.lang.NullPointerException,
                                           java.lang.IllegalArgumentException
        Assert jarURL argument is valid , only supported protocols : jar and file
        Parameters:
        jarURL - URL of JarFile or JarEntry
        Throws:
        java.lang.NullPointerException - If jarURL is null
        java.lang.IllegalArgumentException - If URL.getProtocol() is not jar or file

      • resolveRelativePath

        @Nullable
public static java.lang.String resolveRelativePath​(java.net.URL jarURL)
                                            throws java.lang.NullPointerException,
                                                   java.lang.IllegalArgumentException
        Resolves the relative path from the given JAR URL.

        This method extracts the part of the URL after the archive entry separator (e.g., "!/") and decodes it to provide a normalized relative path within the JAR archive.

        Example Usage

        
 URL jarURL = new URL("jar:file:/path/to/file.jar!/com/example/resource.txt");
 String relativePath = JarUtils.resolveRelativePath(jarURL);
 System.out.println(relativePath);  // Output: com/example/resource.txt
        Parameters:
        jarURL - the URL pointing to a resource within a JAR file; must not be null
        Returns:
        the resolved relative path within the JAR archive
        Throws:
        java.lang.NullPointerException - if the provided jarURL is null
        java.lang.IllegalArgumentException - if the URL protocol is neither "jar" nor "file"

      • resolveJarAbsolutePath

        @Nullable
public static java.lang.String resolveJarAbsolutePath​(java.net.URL jarURL)
                                               throws java.lang.NullPointerException,
                                                      java.lang.IllegalArgumentException
        Resolves the absolute path of the JAR file from the provided URL.

        This method ensures that the URL protocol is either "jar" or "file", and then resolves the absolute path to the corresponding JAR archive on the file system. If the URL does not point to a valid JAR or file resource, this method returns null.

        Example Usage

        
 URL jarURL = new URL("jar:file:/path/to/file.jar!/com/example/resource.txt");
 String absolutePath = JarUtils.resolveJarAbsolutePath(jarURL);
 System.out.println(absolutePath);  // Output: /path/to/file.jar
        Parameters:
        jarURL - the URL pointing to a JAR file or entry; must not be null
        Returns:
        the resolved absolute path of the JAR file if successful, or null if resolution fails
        Throws:
        java.lang.NullPointerException - if the provided jarURL is null
        java.lang.IllegalArgumentException - if the URL protocol is neither "jar" nor "file"

      • filter

        @Nonnull
@Immutable
public static java.util.List<java.util.jar.JarEntry> filter​(java.util.jar.JarFile jarFile,
                                                            JarEntryFilter jarEntryFilter)
        Filters the entries of a JAR file based on the provided JarEntryFilter.

        This method iterates through all entries in the given JAR file and applies the filter to selectively include or exclude entries. If the provided JarFile is null or empty, an empty list is returned.

        Example Usage

        
 JarFile jarFile = new JarFile("example.jar");
 JarEntryFilter classFileFilter = entry -> entry.getName().endsWith(".class");
 List<JarEntry> filteredEntries = JarUtils.filter(jarFile, classFileFilter);
        Parameters:
        jarFile - The source JAR file; may be null.
        jarEntryFilter - The filter used to determine which entries to include; may be null (no filtering).
        Returns:
        A read-only list of filtered JAR entries. Never null.

      • doFilter

        @Nonnull
@Immutable
protected static java.util.List<java.util.jar.JarEntry> doFilter​(java.lang.Iterable<java.util.jar.JarEntry> jarEntries,
                                                                 JarEntryFilter jarEntryFilter)

      • findJarEntry

        @Nullable
public static java.util.jar.JarEntry findJarEntry​(java.net.URL jarURL)
                                           throws java.io.IOException
        Finds and returns the JarEntry from the specified JAR URL.

        This method resolves the relative path within the JAR archive from the provided URL and retrieves the corresponding entry. If the entry does not exist or if there's an issue accessing the JAR file, an exception may be thrown or a null value returned depending on underlying behavior.

        Example Usage

        
 URL jarURL = new URL("jar:file:/path/to/file.jar!/com/example/resource.txt");
 JarEntry jarEntry = JarUtils.findJarEntry(jarURL);
 System.out.println(jarEntry.getName());  // Output: com/example/resource.txt
        Parameters:
        jarURL - the URL pointing to a resource within a JAR file; must not be null
        Returns:
        the resolved JarEntry if found, or null if no such entry exists
        Throws:
        java.io.IOException - if an I/O error occurs while reading the JAR file or resolving the entry

      • extract

        public static void extract​(java.io.File jarSourceFile,
                           java.io.File targetDirectory)
                    throws java.io.IOException
        Extracts the contents of the specified JAR file to the given target directory.

        This method extracts all entries from the provided JAR file into the target directory, preserving the original directory structure. If the JAR file contains nested directories, they will be recreated under the target directory.

        Example Usage

        
 File jarFile = new File("example.jar");
 File outputDir = new File("/path/to/output");
 JarUtils.extract(jarFile, outputDir);
        Parameters:
        jarSourceFile - the source JAR file to extract; must not be null
        targetDirectory - the target directory where contents will be extracted; must not be null
        Throws:
        java.io.IOException - if an I/O error occurs during extraction or if the provided file is not a valid JAR

      • extract

        public static void extract​(java.io.File jarSourceFile,
                           java.io.File targetDirectory,
                           JarEntryFilter jarEntryFilter)
                    throws java.io.IOException
        Extracts the contents of the specified JAR file to the given target directory, optionally filtering entries.

        This method extracts entries from the provided JAR file into the target directory. If a filter is provided, only entries accepted by the filter will be extracted. The original directory structure of the JAR is preserved under the target directory.

        Example Usage

        
 File jarFile = new File("example.jar");
 File outputDir = new File("/path/to/output");

 // Extract all entries
 JarUtils.extract(jarFile, outputDir, null);

 // Extract only .class files
 JarEntryFilter classFileFilter = entry -> entry.getName().endsWith(".class");
 JarUtils.extract(jarFile, outputDir, classFileFilter);
        Parameters:
        jarSourceFile - the source JAR file to extract; must not be null
        targetDirectory - the target directory where contents will be extracted; must not be null
        jarEntryFilter - an optional filter to restrict which entries are extracted; may be null to extract all entries
        Throws:
        java.io.IOException - if an I/O error occurs during extraction or if the provided file is not a valid JAR

      • extract

        public static void extract​(java.util.jar.JarFile jarFile,
                           java.io.File targetDirectory,
                           JarEntryFilter jarEntryFilter)
                    throws java.io.IOException
        Extracts entries from a JAR file to the specified target directory, optionally filtering which entries to extract.

        This method filters the entries in the JAR file using the provided JarEntryFilter, and extracts only those entries that are accepted by the filter. If no filter is provided (i.e., null), all entries will be extracted. The directory structure within the JAR is preserved under the target directory.

        Example Usage

        
 JarFile jarFile = new JarFile("example.jar");
 File outputDir = new File("/path/to/output");

 // Extract all entries
 JarUtils.extract(jarFile, outputDir, null);

 // Extract only .class files
 JarEntryFilter classFileFilter = entry -> entry.getName().endsWith(".class");
 JarUtils.extract(jarFile, outputDir, classFileFilter);
        Parameters:
        jarFile - the source JAR file to extract from; must not be null
        targetDirectory - the directory where the contents should be extracted; must not be null
        jarEntryFilter - an optional filter to determine which entries to extract; if null, all entries are extracted
        Throws:
        java.io.IOException - if an I/O error occurs during extraction or if the JAR file is invalid

      • extract

        public static void extract​(java.net.URL jarResourceURL,
                           java.io.File targetDirectory,
                           JarEntryFilter jarEntryFilter)
                    throws java.io.IOException
        Extracts entries from a JAR resource pointed by the given URL to the specified target directory, optionally filtering which entries to extract.

        This method resolves the JAR file and relative path from the provided URL, filters the entries using the given JarEntryFilter, and extracts them to the target directory while preserving the original directory structure. If no filter is provided (i.e., null), all entries under the resolved path will be extracted.

        Example Usage

        
 URL jarURL = new URL("jar:file:/path/to/file.jar!/com/example/");
 File outputDir = new File("/path/to/output");

 // Extract all entries under 'com/example/'
 JarUtils.extract(jarURL, outputDir, null);

 // Extract only .class files under 'com/example/'
 JarEntryFilter classFileFilter = entry -> entry.getName().endsWith(".class");
 JarUtils.extract(jarURL, outputDir, classFileFilter);
        Parameters:
        jarResourceURL - the URL pointing to a resource within a JAR file; must not be null
        targetDirectory - the directory where the contents should be extracted; must not be null
        jarEntryFilter - an optional filter to determine which entries to extract; if null, all entries are extracted
        Throws:
        java.io.IOException - if an I/O error occurs during extraction or resolving the JAR resource

      • doExtract

        protected static void doExtract​(java.util.jar.JarFile jarFile,
                                java.lang.Iterable<java.util.jar.JarEntry> jarEntries,
                                java.io.File targetDirectory)
                         throws java.io.IOException
        Throws:
        java.io.IOException