0
# Archive Specifications
1

2
Archive specification implementations provide concrete implementations for standard Java archive formats (JAR, WAR, EAR, RAR) with full compliance to their respective specifications.
3

4
## JAR Archives
5

6
### JavaArchiveImpl
7

8
Complete implementation of Java Archive (JAR) format with standard JAR functionality.
9

10
```java { .api }
11
public class JavaArchiveImpl extends ContainerBase<JavaArchive> implements JavaArchive
12
```
13

14
**Constructors:**
15
```java { .api }
16
public JavaArchiveImpl(String archiveName)
17
```
18

19
**Key Features:**
20
- Standard JAR file structure
21
- Manifest handling (META-INF/MANIFEST.MF)
22
- Service provider configuration (META-INF/services/)
23
- Class and resource packaging
24
- Library dependencies
25

26
**Usage Example:**
27
```java
28
JavaArchiveImpl jar = new JavaArchiveImpl("application.jar");
29
jar.addClass(Application.class)
30
   .addPackage("com.example.core")
31
   .addAsResource("config.properties")
32
   .setManifest("META-INF/MANIFEST.MF");
33
```
34

35
## Web Archives
36

37
### WebArchiveImpl
38

39
Complete implementation of Web Archive (WAR) format for web applications.
40

41
```java { .api }
42
public class WebArchiveImpl extends WebContainerBase<WebArchive> implements WebArchive
43
```
44

45
**Constructors:**
46
```java { .api }
47
public WebArchiveImpl(String archiveName)
48
```
49

50
**Web-Specific Structure:**
51
- `/WEB-INF/web.xml` - Web application descriptor
52
- `/WEB-INF/classes/` - Web application classes
53
- `/WEB-INF/lib/` - Web application libraries
54
- Root directory for web resources (HTML, CSS, JS, images)
55

56
**Usage Example:**
57
```java
58
WebArchiveImpl war = new WebArchiveImpl("webapp.war");
59
war.addClass(ServletClass.class)
60
   .addAsWebResource("index.html")
61
   .addAsWebResource("css/style.css", "css/style.css")
62
   .setWebXML("WEB-INF/web.xml")
63
   .addAsLibrary(dependencyJar);
64
```
65

66
## Enterprise Archives
67

68
### EnterpriseArchiveImpl
69

70
Complete implementation of Enterprise Archive (EAR) format for enterprise applications.
71

72
```java { .api }
73
public class EnterpriseArchiveImpl extends EnterpriseContainerBase<EnterpriseArchive> 
74
    implements EnterpriseArchive
75
```
76

77
**Constructors:**
78
```java { .api }
79
public EnterpriseArchiveImpl(String archiveName)
80
```
81

82
**Enterprise Structure:**
83
- `META-INF/application.xml` - Application descriptor
84
- `/lib/` - Shared libraries
85
- Module archives (JAR, WAR, RAR)
86

87
**Usage Example:**
88
```java
89
EnterpriseArchiveImpl ear = new EnterpriseArchiveImpl("enterprise.ear");
90
ear.addAsModule(webModule)
91
   .addAsModule(ejbModule)
92
   .addAsLibrary(sharedLibrary)
93
   .setApplicationXML("META-INF/application.xml");
94
```
95

96
## Resource Adapter Archives
97

98
### ResourceAdapterArchiveImpl
99

100
Complete implementation of Resource Adapter Archive (RAR) format for JCA connectors.
101

102
```java { .api }
103
public class ResourceAdapterArchiveImpl extends ResourceAdapterContainerBase<ResourceAdapterArchive> 
104
    implements ResourceAdapterArchive
105
```
106

107
**Constructors:**
108
```java { .api }
109
public ResourceAdapterArchiveImpl(String archiveName)
110
```
111

112
**RAR Structure:**
113
- `META-INF/ra.xml` - Resource adapter descriptor
114
- Connector implementation classes
115
- Required libraries
116

117
**Usage Example:**
118
```java
119
ResourceAdapterArchiveImpl rar = new ResourceAdapterArchiveImpl("connector.rar");
120
rar.addClass(ResourceAdapterImpl.class)
121
   .addClass(ConnectionFactoryImpl.class)
122
   .setResourceAdapterXML("META-INF/ra.xml");
123
```
124

125
## Specification Compliance
126

127
### JAR Specification Compliance
128

129
JavaArchiveImpl follows JAR File Specification:
130
- Proper MANIFEST.MF format and location
131
- Service provider interface files in META-INF/services/
132
- Signature files support (META-INF/*.SF, *.DSA, *.RSA)
133
- Index files (META-INF/INDEX.LIST)
134

135
### WAR Specification Compliance
136

137
WebArchiveImpl adheres to Servlet Specification:
138
- Required web.xml structure and validation
139
- Proper WEB-INF directory layout
140
- Class loading hierarchy (WEB-INF/classes before WEB-INF/lib)
141
- Tag library descriptor support
142

143
### EAR Specification Compliance
144

145
EnterpriseArchiveImpl follows Java EE Specification:
146
- Application.xml descriptor format
147
- Module type detection and configuration
148
- Library directory handling
149
- Alternative deployment descriptors
150

151
### RAR Specification Compliance
152

153
ResourceAdapterArchiveImpl implements JCA Specification:
154
- Resource adapter descriptor (ra.xml) format
155
- Connector architecture compliance
156
- Transaction and security support structures
157

158
## Archive Type Detection
159

160
The specification implementations include automatic type detection:
161

162
```java
163
// Automatic format detection based on extension and content
164
Archive<?> archive = ArchiveFactory.create("application.war");
165
// Returns WebArchiveImpl instance
166

167
// Explicit type specification
168
JavaArchive jar = ArchiveFactory.create(JavaArchive.class, "app.jar");
169
// Returns JavaArchiveImpl instance
170
```
171

172
## Format Validation
173

174
Each specification implementation includes validation capabilities:
175

176
```java
177
// Validate archive structure
178
ValidationResult result = archive.validate();
179
if (!result.isValid()) {
180
    for (ValidationError error : result.getErrors()) {
181
        System.err.println("Validation error: " + error.getMessage());
182
    }
183
}
184
```
185

186
## Archive Metadata
187

188
Specification implementations provide metadata access:
189

190
```java
191
// JAR-specific metadata
192
String mainClass = jar.getManifest().getMainAttributes().getValue("Main-Class");
193

194
// WAR-specific metadata  
195
String displayName = war.getWebXml().getDisplayName();
196

197
// EAR-specific metadata
198
List<Module> modules = ear.getApplicationXml().getModules();
199
```
200

201
## Content Organization
202

203
### JAR Content Layout
204
```
205
META-INF/
206
  MANIFEST.MF
207
  services/
208
    com.example.Service
209
com/
210
  example/
211
    Application.class
212
config.properties
213
```
214

215
### WAR Content Layout
216
```
217
WEB-INF/
218
  web.xml
219
  classes/
220
    com/example/ServletClass.class
221
  lib/
222
    dependency.jar
223
META-INF/
224
  MANIFEST.MF
225
index.html
226
css/
227
  style.css
228
```
229

230
### EAR Content Layout
231
```
232
META-INF/
233
  application.xml
234
  MANIFEST.MF
235
lib/
236
  shared-library.jar
237
webapp.war
238
ejb-module.jar
239
connector.rar
240
```
241

242
### RAR Content Layout
243
```
244
META-INF/
245
  ra.xml
246
  MANIFEST.MF
247
com/
248
  example/
249
    ResourceAdapterImpl.class
250
    ConnectionFactoryImpl.class
251
```
252

253
## Integration with ShrinkWrap API
254

255
The specification implementations integrate seamlessly with the broader ShrinkWrap API:
256

257
```java
258
// Create using ShrinkWrap factory
259
JavaArchive jar = ShrinkWrap.create(JavaArchive.class, "app.jar");
260

261
// Convert between types
262
WebArchive war = jar.as(WebArchive.class);
263

264
// Export to different formats
265
File jarFile = jar.as(ZipExporter.class).exportToFile("app.jar");
266
```
267

268
## Custom Specification Extensions
269

270
The base classes support creating custom specifications:
271

272
```java
273
public class CustomArchiveImpl extends ContainerBase<CustomArchive> 
274
    implements CustomArchive {
275
    
276
    public CustomArchiveImpl(String archiveName) {
277
        super(archiveName, CustomArchive.class);
278
    }
279
    
280
    // Custom specification-specific methods
281
    public CustomArchive setCustomDescriptor(Asset descriptor) {
282
        return add(descriptor, new BasicPath("/META-INF/custom.xml"));
283
    }
284
}
285
```