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