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 */
25package jdk.tools.jlink.plugin;
26
27import java.io.InputStream;
28import java.io.IOException;
29import java.io.OutputStream;
30import java.io.UncheckedIOException;
31import java.nio.file.Path;
32
33import 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 */
48public 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     * </li>
62     */
63    public enum Type {
64        CLASS_OR_RESOURCE,
65        CONFIG,
66        HEADER_FILE,
67        LEGAL_NOTICE,
68        MAN_PAGE,
69        NATIVE_CMD,
70        NATIVE_LIB,
71        TOP
72    }
73
74    /**
75     * The module name of this ResourcePoolEntry.
76     *
77     * @return The module name.
78     */
79    public String moduleName();
80
81    /**
82     * The path of this ResourcePoolEntry.
83     *
84     * @return The module path.
85     */
86    public String path();
87
88    /**
89     * The ResourcePoolEntry's type.
90     *
91     * @return The data type.
92     */
93    public Type type();
94
95    /**
96     * The ResourcePoolEntry content length.
97     *
98     * @return The content length.
99     */
100    public long contentLength();
101
102    /**
103     * The ResourcePoolEntry content as an InputStream.
104     *
105     * @return The resource content as an InputStream.
106     */
107    public InputStream content();
108
109    /**
110     * Returns a target linked with this entry.
111     *
112     * @implSpec The default implementation returns {@code null}.
113     *
114     * @return the target ResourcePoolEntry linked with this entry.
115     */
116    public default ResourcePoolEntry linkedTarget() {
117        return null;
118    }
119
120    /**
121     * The ResourcePoolEntry content as an array of bytes.
122     *
123     * @return An Array of bytes.
124     */
125    public default byte[] contentBytes() {
126        try (InputStream is = content()) {
127            return is.readAllBytes();
128        } catch (IOException ex) {
129            throw new UncheckedIOException(ex);
130        }
131    }
132
133    /**
134     * Write the content of this ResourcePoolEntry to an OutputStream.
135     *
136     * @param out the output stream
137     */
138    public default void write(OutputStream out) {
139        try {
140            out.write(contentBytes());
141        } catch (IOException ex) {
142            throw new UncheckedIOException(ex);
143        }
144    }
145
146    /**
147     * Create a ResourcePoolEntry with new content but other information
148     * copied from this ResourcePoolEntry.
149     *
150     * @param content The new resource content.
151     * @return A new ResourcePoolEntry.
152     */
153    public default ResourcePoolEntry copyWithContent(byte[] content) {
154        return ResourcePoolEntryFactory.create(this, content);
155    }
156
157    /**
158     * Create a ResourcePoolEntry with new content but other information
159     * copied from this ResourcePoolEntry.
160     *
161     * @param file The new resource content.
162     * @return A new ResourcePoolEntry.
163     */
164    public default ResourcePoolEntry copyWithContent(Path file) {
165        return ResourcePoolEntryFactory.create(this, file);
166    }
167
168    /**
169     * Create a ResourcePoolEntry for a resource of the given type.
170     *
171     * @param path The resource path.
172     * @param type The ResourcePoolEntry type.
173     * @param content The resource content.
174     * @return A new ResourcePoolEntry.
175     */
176    public static ResourcePoolEntry create(String path,
177            ResourcePoolEntry.Type type, byte[] content) {
178        return ResourcePoolEntryFactory.create(path, type, content);
179    }
180
181    /**
182     * Create a ResourcePoolEntry for a resource of type {@link Type#CLASS_OR_RESOURCE}.
183     *
184     * @param path The resource path.
185     * @param content The resource content.
186     * @return A new ResourcePoolEntry.
187     */
188    public static ResourcePoolEntry create(String path, byte[] content) {
189        return create(path, Type.CLASS_OR_RESOURCE, content);
190    }
191
192    /**
193     * Create a ResourcePoolEntry for a resource of the given type.
194     *
195     * @param path The resource path.
196     * @param type The ResourcePoolEntry type.
197     * @param file The resource file.
198     * @return A new ResourcePoolEntry.
199     */
200    public static ResourcePoolEntry create(String path,
201            ResourcePoolEntry.Type type, Path file) {
202        return ResourcePoolEntryFactory.create(path, type, file);
203    }
204
205    /**
206     * Create a ResourcePoolEntry for a resource of type {@link Type#CLASS_OR_RESOURCE}.
207     *
208     * @param path The resource path.
209     * @param file The resource file.
210     * @return A new ResourcePoolEntry.
211     */
212    public static ResourcePoolEntry create(String path, Path file) {
213        return create(path, Type.CLASS_OR_RESOURCE, file);
214    }
215
216    /**
217     * Create a ResourcePoolEntry for a resource the given path and type.
218     * If the target platform supports symbolic links, it will be created
219     * as a symbolic link to the given target entry; otherwise, the
220     * ResourcePoolEntry contains the relative path to the target entry.
221     *
222     * @param path The resource path.
223     * @param type The ResourcePoolEntry type.
224     * @param target The target entry
225     * @return A new ResourcePoolEntry
226     */
227    public static ResourcePoolEntry createSymLink(String path,
228                                                  ResourcePoolEntry.Type type,
229                                                  ResourcePoolEntry target) {
230        return ResourcePoolEntryFactory.createSymbolicLink(path, type, target);
231    }
232}
233