0
# Archive Base Classes
1

2
The archive base classes provide foundational implementations for all ShrinkWrap archive types. These abstract classes handle core functionality including memory management, content operations, and thread safety.
3

4
## Core Base Classes
5

6
### MemoryMapArchiveBase<T>
7

8
Thread-safe memory-based archive storage implementation that serves as the foundation for most archive types.
9

10
```java { .api }
11
public abstract class MemoryMapArchiveBase<T extends Archive<T>> extends ArchiveBase<T>
12
```
13

14
**Key Features:**
15
- In-memory content storage using LinkedHashMap
16
- Thread-safe operations with synchronized access
17
- Support for archive events and handlers
18
- Content merging and filtering capabilities
19

20
**Common Usage:**
21
```java
22
// Extend for custom archive implementations
23
public class CustomArchiveImpl extends MemoryMapArchiveBase<CustomArchive> {
24
    public CustomArchiveImpl(String archiveName) {
25
        super(archiveName, CustomArchive.class);
26
    }
27
}
28
```
29

30
### AssignableBase<T>
31

32
Base implementation for archives that support type conversion through the `as()` method.
33

34
```java { .api }
35
public abstract class AssignableBase<T extends Assignable> implements Assignable
36
```
37

38
**Key Methods:**
39
```java { .api }
40
public <TYPE extends Assignable> TYPE as(Class<TYPE> clazz)
41
```
42

43
**Usage Example:**
44
```java
45
// Convert archive to different exporter type
46
InputStream stream = archive.as(ZipExporter.class).exportAsInputStream();
47
```
48

49
### ArchiveBase<T>
50

51
Root abstract class providing common archive operations and implementing core interfaces.
52

53
```java { .api }
54
public abstract class ArchiveBase<T extends Archive<T>> implements Archive<T>, Configurable, ArchiveFormatAssociable, Identifiable
55
```
56

57
**Core Operations:**
58
- Content addition and retrieval
59
- Path-based access to archive nodes
60
- Archive merging and filtering
61
- Configuration management
62

63
## Support Classes
64

65
### ServiceExtensionLoader
66

67
Loads ShrinkWrap extensions using the Java ServiceLoader pattern.
68

69
```java { .api }
70
public class ServiceExtensionLoader implements ExtensionLoader
71
```
72

73
**Key Methods:**
74
```java { .api }
75
public <T> Collection<T> load(Class<T> serviceClass, ClassLoader classLoader)
76
public void addOverride(Class<?> serviceClass, Class<?> implementationClass)
77
```
78

79
**Usage:**
80
```java
81
ServiceExtensionLoader loader = new ServiceExtensionLoader();
82
Collection<ZipExporter> exporters = loader.load(ZipExporter.class, classLoader);
83
```
84

85
### URLPackageScanner
86

87
Scans packages from URLs for class discovery and dynamic loading.
88

89
```java { .api }
90
public class URLPackageScanner
91
```
92

93
**Key Methods:**
94
```java { .api }
95
public static Set<Class<?>> scanPackage(String packageName, ClassLoader classLoader)
96
public static Set<String> getClassNamesFromJar(URL jarUrl, String packageName)
97
```
98

99
### NodeImpl
100

101
Implementation of the Archive Node interface representing archive entries.
102

103
```java { .api }
104
public class NodeImpl implements Node
105
```
106

107
**Key Methods:**
108
```java { .api }
109
public ArchivePath getPath()
110
public Asset getAsset()
111
public Set<Node> getChildren()
112
public Node getChild(ArchivePath path)
113
```
114

115
**Usage:**
116
```java
117
Node node = new NodeImpl(new BasicPath("/META-INF"), asset);
118
Set<Node> children = node.getChildren();
119
```
120

121
## Configuration and Utilities
122

123
### ExtensionWrapper
124

125
Wrapper for extension instances providing lazy loading and caching.
126

127
```java { .api }
128
public class ExtensionWrapper<T>
129
```
130

131
### ArchiveFormatStreamBindings
132

133
Manages bindings between archive formats and their associated stream handlers.
134

135
```java { .api }
136
public class ArchiveFormatStreamBindings
137
```
138

139
**Key Methods:**
140
```java { .api }
141
public static void bind(ArchiveFormat format, Class<? extends StreamExporter> exporterClass)
142
public static Class<? extends StreamExporter> getExporterClass(ArchiveFormat format)
143
```
144

145
## Exception Handling
146

147
### ExtensionLoadingException
148

149
Runtime exception thrown when extension loading fails.
150

151
```java { .api }
152
public class ExtensionLoadingException extends RuntimeException
153
```
154

155
**Constructors:**
156
```java { .api }
157
public ExtensionLoadingException(String message)
158
public ExtensionLoadingException(String message, Throwable cause)
159
```
160

161
**Common Scenarios:**
162
- Service loader failures
163
- Missing extension classes
164
- Configuration errors
165

166
## Thread Safety
167

168
All base classes are designed with thread safety in mind:
169

170
- **MemoryMapArchiveBase**: Uses synchronized access to internal content map
171
- **ServiceExtensionLoader**: Thread-safe service loading and caching
172
- **NodeImpl**: Immutable node structure with thread-safe operations
173

174
## Extension Points
175

176
The base classes provide several extension points for custom implementations:
177

178
1. **Custom Archive Types**: Extend `MemoryMapArchiveBase` for new archive formats
179
2. **Extension Loading**: Override `ServiceExtensionLoader` for custom loading logic  
180
3. **Node Implementation**: Extend `NodeImpl` for specialized archive entry behavior
181
4. **Configuration**: Implement custom configuration providers through the base interfaces