docs(JAR): explain what a JAR file is with examples

What
- Documented **JAR (Java ARchive)** files as packaged archives for Java applications and libraries.
- Key features:
  - File extension `.jar`.
  - Bundles multiple `.class` files, resources (images, configs), and metadata into a single archive.
  - Built on ZIP format with a special `META-INF/MANIFEST.MF` file.
  - Used for distribution, deployment, and execution of Java programs.
  - Can be executable (with a Main-Class entry) or non-executable (used as a library).

Why
- Simplifies distribution by combining many class files/resources into one file.
- Enables reusability of code as libraries (e.g., external dependencies).
- Supports portability across platforms with the JVM.
- Provides versioning and metadata for deployment tools.

How
- **Creating a JAR file:**
  1. Compile Java program:
     ```
     javac Main.java
     ```
  2. Package into JAR:
     ```
     jar cfe MyApp.jar Main Main.class
     ```
     - `c` → create archive.
     - `f` → output to file.
     - `e` → specify entry point (Main-Class).

java -jar MyApp.jar

jar tf MyApp.jar

Lists files inside archive.

Examples
1. **Hello World executable JAR**
 - `Main.java`:
   ```java
   public class Main {
       public static void main(String[] args) {
           System.out.println("Hello, World from JAR!");
       }
   }
   ```
 - Compile and package:
   ```
   javac Main.java
   jar cfe Hello.jar Main Main.class
   java -jar Hello.jar
   ```
 - Output:
   ```
   Hello, World from JAR!
   ```

2. **Library JAR**
 - Create utility classes, bundle into `Utils.jar`.
 - Add to another project’s classpath:
   ```
   java -cp .;Utils.jar MyApp
   ```

Logic
- Inputs: compiled `.class` files and resources.
- Outputs: compressed `.jar` archive.
- Flow:
1. Java compiler generates `.class`.
2. jar tool packages classes/resources into `.jar`.
3. JVM runs `java -jar` if Main-Class is defined.
- Edge cases:
- Without Main-Class in manifest, `java -jar` fails.
- Paths with spaces must be quoted.
- Complexity / performance:
- Simple ZIP compression; overhead minimal.
- Concurrency / thread-safety:
- Multiple JARs can be used simultaneously on the classpath.

Real-life applications
- Delivering Java applications as single executable files.
- Packaging reusable libraries (e.g., `gson.jar`, `mysql-connector.jar`).
- Used in build tools (Maven, Gradle) for dependency management.
- Required in Java EE/ Jakarta EE deployments (WAR/EAR contain JARs internally).

Notes
- Executable JAR requires `META-INF/MANIFEST.MF` with Main-Class specified.
- Non-executable JARs serve as libraries only, added to classpath.
- JARs can be signed for integrity and security.
- Still widely used even with newer formats (like JMOD in Java 9+).

Signed-off-by: https://github.com/Someshdiwan <[email protected]>

Author: Someshdiwan

Tips And Tricks/Jar File Java.txt

@@ -0,0 +1,196 @@
+What is a JAR file?
+
+A JAR (Java ARchive) is a package file format (based on ZIP) used to bundle Java classes, resources, and
+metadata into a single file.
+
+A JAR makes it easy to distribute Java libraries, applications, and resources as one portable unit.
+
+Key characteristics:
+	•	ZIP-based archive (.jar).
+	•	Contains compiled .class files, resource files (properties, images), and an optional META-INF/MANIFEST.MF.
+	•	Can be executed (if it contains a Main-Class entry in the manifest) or used as a library on the classpath.
+
+Why JAR files are important
+	•	Distribution — package everything needed (classes + resources) into one file for easy sharing and deployment.
+	•	Reproducibility — stable artifact that can be versioned and archived.
+	•	Classpath management — simplifies dependency handling (one file instead of many loose class files).
+	•	Security & Integrity — supports signing (JAR signing) and manifest metadata.
+	•	Performance — fewer filesystem entries and easier I/O handling; commonly used by class loaders.
+	•	Tooling compatibility — all build tools (Maven, Gradle, Ant), application servers, and the JVM understand JARs.
+
+Basic JAR layout
+
+A typical JAR structure:
+
+myapp.jar
+├─ META-INF/
+│  ├─ MANIFEST.MF     <-- manifest file (metadata)
+│  └─ (optional signatures, other metadata)
+├─ com/example/App.class
+├─ com/example/Utils.class
+├─ config/app.properties
+└─ images/logo.png
+
+Important manifest entries (META-INF/MANIFEST.MF)
+
+A manifest is a small text file containing key-value pairs. Common entries:
+	•	Manifest-Version: 1.0
+	•	Main-Class: com.example.App — makes the jar executable (java -jar myapp.jar).
+	•	Class-Path: lib/foo.jar lib/bar.jar — reference other jars (space separated) relative to the jar.
+	•	Implementation-Version, Implementation-Title, Built-By, Created-By — useful metadata.
+	•	Sealed: true (package sealing), Multi-Release: true (multi-release JARs).
+
+Creating and running JARs — basic commands
+
+Using the JDK jar tool (manual / small projects):
+	1.	Create a JAR (pack classes and resources):
+
+jar cf myapp.jar -C out/classes .
+
+c = create, f = specify filename, -C out/classes . = change dir to compiled classes.
+	2.	Create a JAR with an explicit manifest (executable):
+
+	•	Create manifest.txt:
+
+Manifest-Version: 1.0
+Main-Class: com.example.Main
+
+	•	Build jar:
+
+jar cfm myapp.jar manifest.txt -C out/classes .
+
+m = include manifest file.
+	3.	Run an executable JAR:
+
+java -jar myapp.jar
+
+	4.	List contents of a jar:
+
+jar tf myapp.jar
+
+	5.	Extract a jar:
+
+jar xf myapp.jar
+
+Using build tools (recommended for real projects)
+	•	Maven: mvn package builds a JAR (and can configure an executable “fat” JAR via maven-shade-plugin or
+	    spring-boot-maven-plugin).
+	•	Gradle: gradle jar for plain jar, or gradle shadowJar (with Shadow plugin) to create a fat/uber JAR.
+	•	These tools handle dependency resolution, manifest generation, resource filtering, and reproducible builds.
+
+Types of JARs
+	•	Library JAR — contains classes/resources for use by other apps (not necessarily executable).
+	•	Executable JAR — contains Main-Class in manifest; runnable with java -jar.
+	•	Fat / Uber JAR — bundles project classes plus all dependencies in one large JAR
+	    (useful for single-file deployment). Tools: Maven Shade, Gradle Shadow.
+	•	Modular JAR — contains module-info.class and follows Java Platform Module System (JPMS).
+	    Used with java --module-path.
+	•	Multi-Release JAR (MRJAR) — allows including version-specific class files under META-INF/versions/ for use
+	    on different Java versions.
+	•	Signed JAR — signed with jarsigner for authenticity/integrity.
+
+Classpath & class loading
+	•	A JAR becomes usable by adding it to the classpath: java -cp mylib.jar;myapp.jar com.example.Main.
+	•	java -jar ignores the -cp option and uses the manifest’s Class-Path plus the jar itself.
+	•	Class loaders load classes from JARs; order matters. Conflicting classes across jars cause “classpath hell”.
+
+Executable JAR gotchas
+	•	java -jar uses only the manifest classpath and ignores -cp — if you need additional jars,
+	    either set Class-Path in the manifest or use -cp with a main class.
+	•	Fat jars make deployment simpler but can cause duplicate resource/class conflicts —
+	    use shading to relocate packages if necessary.
+
+Jar signing & security
+	•	Sign a JAR using jarsigner (provides origin & integrity verification).
+	•	Signed JARs are required for applets or for some secure environments.
+	•	Signing adds .SF, .RSA/.DSA files into META-INF/.
+
+Modular jars & JPMS
+	•	Introduced in Java 9. A modular jar contains a module-info.class.
+	•	Run with module path: java --module-path mods -m com.example/com.example.Main.
+	•	Modules help strong encapsulation and reliable configuration; however many existing libraries are still
+	    non-modular.
+
+Best practices
+	•	Use Maven/Gradle for build and dependency management — they produce consistent JARs and handle manifests.
+	•	Prefer library jars (small, focused) for reuse. Use fat jars for easy deployment where appropriate
+	    (microservices, small utilities).
+	•	Keep the manifest minimal and correct; set Main-Class only when building an executable jar.
+	•	Use semantic versioning in jar filenames/dependency coordinates.
+	•	Avoid mixing many unrelated dependencies into a single fat jar unless necessary.
+	•	If using fat jars, use shading/relocation to avoid dependency conflicts.
+	•	Test your jar locally before releasing (verify java -jar, classpath resolution).
+	•	Sign only when you need to verify publisher identity; manage keys carefully.
+
+Common issues & troubleshooting
+	•	NoClassDefFoundError or ClassNotFoundException: missing dependency on classpath or improper manifest Class-Path.
+	•	Could not find or load main class: wrong Main-Class in manifest or wrong package/class name.
+	•	Duplicate classes/resource conflicts in fat jars — use shading or exclude duplicates.
+	•	Incorrect manifest format: manifest lines must end with \r\n/\n and a blank line at the end;
+	    long values are wrapped using continued-line syntax.
+	•	java -jar ignores environment CLASSPATH for security/consistency (older versions behave differently).
+	•	Permission issues on Windows/macOS when executing jar — ensure java is on PATH and file permissions allow reading.
+
+Useful commands & tools
+	•	jar (JDK): cf, tf, xf, uf, cfm etc.
+	•	jarsigner (JDK): sign/verify jars.
+	•	jdeps (JDK): dependency analysis and module detection.
+	•	jlink (JDK): create custom runtime images (smaller, runtime+modules).
+	•	unzip / zip — you can open and inspect jar like any zip file.
+	•	Build tools: Maven, Gradle, Ant.
+	•	Plugins: Maven Shade, Gradle Shadow for fat JARs.
+
+Examples (practical)
+	1.	Create an executable jar from compiled classes:
+
+# assume classes in out/production/myapp
+echo "Manifest-Version: 1.0" > manifest.txt
+echo "Main-Class: com.example.Main" >> manifest.txt
+jar cfm myapp.jar manifest.txt -C out/production/myapp .
+java -jar myapp.jar
+
+	2.	Create a fat jar with Maven (pom.xml plugin snippet, conceptual):
+
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-shade-plugin</artifactId>
+  <version>3.2.4</version>
+  <executions><execution><phase>package</phase><goals><goal>shade</goal></goals></execution></executions>
+</plugin>
+
+	3.	Inspect dependencies:
+
+jdeps --multi-release 9 -s myapp.jar
+
+JAR vs WAR vs EAR
+	•	JAR — general Java archive for libraries and standalone apps.
+	•	WAR — Web Application Archive, used for web apps (Servlets), deployable to servlet containers
+	    (Tomcat); has WEB-INF/.
+	•	EAR — Enterprise Archive for Java EE applications; bundles EJBs, WARs, libraries.
+
+Performance & packaging notes
+	•	Multiple small jars increase filesystem overhead; a single jar can be simpler but less modular.
+	•	Class loader performance and startup time can be affected by the number of jars.
+	•	Using jlink to produce runtime images can drastically reduce deployment size when using modules.
+
+Advanced topics (brief)
+	•	Multi-release JARs: provide version-specific implementations under META-INF/versions/.
+	•	Class-Path tricks: manifest Class-Path can reference external jars (relative paths).
+	•	Jar sealing: mark packages as sealed so all classes for a package come from the same jar.
+	•	Signed jars & Certificate Management: manage keystores, rotate keys, and verify signatures.
+
+Quick Checklist for Building a Reliable JAR
+	•	Use a build tool (Maven/Gradle/Ant).
+	•	Include only needed dependencies; prefer modular jar layout where practical.
+	•	Define Main-Class if jar should be executable.
+	•	Test run with java -jar and via classpath usage.
+	•	If producing a fat jar, handle duplicate packages (use shading).
+	•	Optionally sign jar if distribution requires authenticity.
+	•	Add semantic version to artifact coordinates/filename and include build metadata in MANIFEST.MF.
+
+Recommended further reading / next steps
+	•	Read the JDK jar tool docs and jlink docs.
+	•	Learn how your build tool (Maven/Gradle) creates jars and how to configure plugins (shade, assembly).
+	•	Experiment with modular jars and module-info.java if you target Java 9+ and want strong encapsulation.
+
+⸻