1 package com.atlassian.plugin;
2
3 import java.io.InputStream;
4 import java.io.File;
5
6 /**
7 * Allows the retrieval of files and/or an input stream of a plugin artifact. Implementations
8 * must allow multiple calls to {@link #getInputStream()}.
9 *
10 * @see PluginController
11 * @since 2.0.0
12 */
13 public interface PluginArtifact
14 {
15 /**
16 * @return true if the resource exists in this artifact, otherwise false
17 * @since 2.2.0
18 */
19 boolean doesResourceExist(String name);
20
21 /**
22 * @return an input stream of the resource specified inside the artifact. Null if the resource cannot be found.
23 * @throws PluginParseException if the there was an exception retrieving the resource from the artifact
24 */
25 InputStream getResourceAsStream(String name) throws PluginParseException;
26
27 /**
28 * @return the original name of the plugin artifact file. Typically used
29 * for persisting it to disk with a meaningful name.
30 */
31 String getName();
32
33 /**
34 * @return an InputStream for the entire plugin artifact. Calling this
35 * multiple times will return a fresh input stream each time.
36 */
37 InputStream getInputStream();
38
39 /**
40 * @return the artifact as a file, or its underlying file if it is already one
41 * @since 2.2.0
42 */
43 File toFile();
44
45 /**
46 * @return {@code true} if the plugin contains or references java executable code.
47 * @since 3.0
48 */
49 boolean containsJavaExecutableCode();
50
51 /**
52 * Additional interface for a plugin artifact which may support reference installation.
53 */
54 interface AllowsReference
55 {
56 /**
57 * A named boolean for specifying {@link PluginArtifact.AllowsReference#allowsReference}
58 * return values.
59 */
60 enum ReferenceMode
61 {
62 /** {@link AllowsReference#allowsReference} returns false. */
63 FORBID_REFERENCE(false),
64
65 /** {@link PluginArtifact.AllowsReference#allowsReference} returns true. */
66 PERMIT_REFERENCE(true);
67
68 private boolean allowsReference;
69
70 private ReferenceMode(boolean allowsReference)
71 {
72 this.allowsReference = allowsReference;
73 }
74
75 boolean allowsReference()
76 {
77 return allowsReference;
78 }
79 }
80
81 /**
82 * Query whether or not the PluginArtifact may be reference installed.
83 *
84 * @return true iff the artifact may be reference installed.
85 */
86 boolean allowsReference();
87
88 /**
89 * Host class for a static accessor which defaults allowsReference to false.
90 */
91 class Default
92 {
93 /**
94 * Determine if a PluginArtifact allows reference installation.
95 *
96 * If the PluginArtifact supports AllowsReference, it's allowsReference is queried, otherwise
97 * it defaults to false.
98 *
99 * @param pluginArtifact the plugin artifact to check.
100 * @return true iff a reference install should be attempted for pluginArtifact.
101 */
102 public static boolean allowsReference(PluginArtifact pluginArtifact)
103 {
104 return (pluginArtifact instanceof PluginArtifact.AllowsReference) &&
105 ((PluginArtifact.AllowsReference) pluginArtifact).allowsReference();
106 }
107 }
108 }
109 }