1 /*
2 * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package jdk.tools.jlink.plugin;
26
27 import java.io.InputStream;
28 import java.io.IOException;
29 import java.io.OutputStream;
30 import java.io.UncheckedIOException;
31 import java.nio.file.Path;
32
33 import jdk.tools.jlink.internal.ResourcePoolEntryFactory;
34
35 /**
36 * A ResourcePoolEntry is the elementary unit of data inside an image. It is
37 * generally a file. e.g.: a java class file, a resource file, a shared library.
38 * <br>
39 * A ResourcePoolEntry is identified by a path of the form:
40 * <ul>
41 * <li>For jimage content: /{module name}/{package1}/.../{packageN}/{file
42 * name}</li>
43 * <li>For top-level files:/{module name}/{file name}</li>
44 * <li>For other files (shared lib, launchers, config, ...):/{module name}/
45 * {@literal bin|conf|native}/{dir1}/.../{dirN}/{file name}</li>
46 * </ul>
47 */
48 public interface ResourcePoolEntry {
49
50 /**
51 * Type of module data.
52 * <li>
53 * <ul>CLASS_OR_RESOURCE: A java class or resource file.</ul>
54 * <ul>CONFIG: A configuration file.</ul>
55 * <ul>HEADER_FILE: A header file.</ul>
56 * <ul>LEGAL_NOTICE: A legal notice.</ul>
57 * <ul>MAN_PAGE: A man page.</ul>
58 * <ul>NATIVE_CMD: A native executable launcher.</ul>
59 * <ul>NATIVE_LIB: A native library.</ul>
60 * <ul>TOP: A top-level file in the jdk run-time image directory.</ul>
61 * <ul>OTHER: Other kind of file.</ul>
62 * </li>
63 */
64 public enum Type {
65 CLASS_OR_RESOURCE,
66 CONFIG,
67 HEADER_FILE,
68 LEGAL_NOTICE,
69 MAN_PAGE,
70 NATIVE_CMD,
71 NATIVE_LIB,
72 TOP,
73 OTHER
74 }
75
76 /**
77 * The module name of this ResourcePoolEntry.
78 *
79 * @return The module name.
80 */
81 public String moduleName();
82
83 /**
84 * The path of this ResourcePoolEntry.
85 *
86 * @return The module path.
87 */
88 public String path();
89
90 /**
91 * The ResourcePoolEntry's type.
92 *
93 * @return The data type.
94 */
95 public Type type();
96
97 /**
98 * The ResourcePoolEntry content length.
99 *
100 * @return The content length.
101 */
102 public long contentLength();
103
104 /**
105 * The ResourcePoolEntry content as an InputStream.
106 *
107 * @return The resource content as an InputStream.
108 */
109 public InputStream content();
110
111 /**
112 * Returns a target linked with this entry.
113 *
114 * @implSpec The default implementation returns {@code null}.
115 *
116 * @return the target ResourcePoolEntry linked with this entry.
117 */
118 public default ResourcePoolEntry linkedTarget() {
119 return null;
120 }
121
122 /**
123 * The ResourcePoolEntry content as an array of bytes.
124 *
125 * @return An Array of bytes.
126 */
127 public default byte[] contentBytes() {
128 try (InputStream is = content()) {
129 return is.readAllBytes();
130 } catch (IOException ex) {
131 throw new UncheckedIOException(ex);
132 }
133 }
134
135 /**
136 * Write the content of this ResourcePoolEntry to an OutputStream.
137 *
138 * @param out the output stream
139 */
140 public default void write(OutputStream out) {
141 try {
142 out.write(contentBytes());
143 } catch (IOException ex) {
144 throw new UncheckedIOException(ex);
145 }
146 }
147
148 /**
149 * Create a ResourcePoolEntry with new content but other information
150 * copied from this ResourcePoolEntry.
151 *
152 * @param content The new resource content.
153 * @return A new ResourcePoolEntry.
154 */
155 public default ResourcePoolEntry copyWithContent(byte[] content) {
156 return ResourcePoolEntryFactory.create(this, content);
157 }
158
159 /**
160 * Create a ResourcePoolEntry with new content but other information
161 * copied from this ResourcePoolEntry.
162 *
163 * @param file The new resource content.
164 * @return A new ResourcePoolEntry.
165 */
166 public default ResourcePoolEntry copyWithContent(Path file) {
167 return ResourcePoolEntryFactory.create(this, file);
168 }
169
170 /**
171 * Create a ResourcePoolEntry for a resource of the given type.
172 *
173 * @param path The resource path.
174 * @param type The ResourcePoolEntry type.
175 * @param content The resource content.
176 * @return A new ResourcePoolEntry.
177 */
178 public static ResourcePoolEntry create(String path,
179 ResourcePoolEntry.Type type, byte[] content) {
180 return ResourcePoolEntryFactory.create(path, type, content);
181 }
182
183 /**
184 * Create a ResourcePoolEntry for a resource of type {@link Type#CLASS_OR_RESOURCE}.
185 *
186 * @param path The resource path.
187 * @param content The resource content.
188 * @return A new ResourcePoolEntry.
189 */
190 public static ResourcePoolEntry create(String path, byte[] content) {
191 return create(path, Type.CLASS_OR_RESOURCE, content);
192 }
193
194 /**
195 * Create a ResourcePoolEntry for a resource of the given type.
196 *
197 * @param path The resource path.
198 * @param type The ResourcePoolEntry type.
199 * @param file The resource file.
200 * @return A new ResourcePoolEntry.
201 */
202 public static ResourcePoolEntry create(String path,
203 ResourcePoolEntry.Type type, Path file) {
204 return ResourcePoolEntryFactory.create(path, type, file);
205 }
206
207 /**
208 * Create a ResourcePoolEntry for a resource of type {@link Type#CLASS_OR_RESOURCE}.
209 *
210 * @param path The resource path.
211 * @param file The resource file.
212 * @return A new ResourcePoolEntry.
213 */
214 public static ResourcePoolEntry create(String path, Path file) {
215 return create(path, Type.CLASS_OR_RESOURCE, file);
216 }
217
218 /**
219 * Create a ResourcePoolEntry for a resource the given path and type.
220 * If the target platform supports symbolic links, it will be created
221 * as a symbolic link to the given target entry; otherwise, the
222 * ResourcePoolEntry contains the relative path to the target entry.
223 *
224 * @param path The resource path.
225 * @param type The ResourcePoolEntry type.
226 * @param target The target entry
227 * @return A new ResourcePoolEntry
228 */
229 public static ResourcePoolEntry createSymLink(String path,
230 ResourcePoolEntry.Type type,
231 ResourcePoolEntry target) {
232 return ResourcePoolEntryFactory.createSymbolicLink(path, type, target);
233 }
234 }