Änderungen von Dokument FORMCYCLE-Deploy-Plugin-Plugin

Von Version < 1.11 >
bearbeitet von awa
am 12.03.2020, 11:09
Auf Version < 1.13 >
bearbeitet von awa
am 12.03.2020, 11:56
< >
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -16,6 +16,8 @@
16 16  
17 17  Standardmäßig ist eine Servlet-Aktion für alle frei zugänglich. Da es in der Regel unerwünscht ist, dass jeder (auch unangemeldete) Nutzer Plugins installieren kann, kann das Deploy-Plugin durch ein Passwort abgesichert werden. Dazu muss in der Plugin-Konfiguration der Passwort-Hash hinterlegt werden und das Passwort dann im HTTP-POST-Request mitgesendet werden.
18 18  
19 +== Plugin-Konfiguration ==
20 +
19 19  == HTTP-Request-Aufbau ==
20 20  
21 21  Im Folgenden wird der Aufbau des HTTP-Requests beschrieben, um ein Plugin zu installieren, zu aktualisieren oder zu löschen.
... ... @@ -28,7 +28,7 @@
28 28  
29 29  Die //client-id// muss nicht angegeben werden, wenn das Plugin als System-Plugin installiert ist.
30 30  
31 -=== Request-Parameter
33 +=== Request-Parameter ===
32 32  
33 33  Die Parameter können direkt als URL-Parameter, als //multipart/form-data// oder als //application/x-www-form-urlencoded// übergeben werden. Folgende Parameter werden vom Deploy-Plugin unterstützt und können übergeben werden:
34 34  
... ... @@ -57,9 +57,9 @@
57 57  :; plugin-ident=manifest
58 58  :: //plugin-identifier// muss den Namen der Manifest-Eigenschaft und dessen Wert enthalten, im Format //ATTRIBUTE_NAME=VALUE//. Wird zum Beispiel //Implementation-Title=com.example.fc.plugin:my-plugin// übergeben wird, wird nach einem existierenden Plugin gesucht, welches im Manifest in der Eigenschaft //Implementation-Title// den Wert //com.example.fc.plugin:my-plugin// stehen hat.
59 59  :; plugin-ident=id
60 -:: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.
62 +:: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.//
61 61  :; plugin-ident=name
62 -:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.
64 +:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.//
63 63  :; plugin-ident=uuid
64 64  :: //plugin-identifier// muss die gewünschte UUID des Plugins enthalten, etwa //03022599-903d-429b-9822-80a324a542fc//.
65 65  Andernfalls wird das Plugin installiert, falls noch nicht vorhanden, oder aktualisiert, falls vorhanden.
... ... @@ -71,16 +71,17 @@
71 71  : Entweder //true// oder //false//. Ist diese Option auf //true// gesetzt und existiert das Plugin noch nicht (bezüglich der angegebenen //plugin-ident// und //plugin-identifier//), wird das Plugin nicht neu installiert und eine Fehlermeldung zurückgegeben. ; locale
72 72  : Die Sprache, welche während der Installation, Aktualisierung oder Löschung des Plugins verwendet werden soll, etwa //en// oder //de//. Beeinflusst nur einige Fehlermeldungen und kann in der Regel weggelassen werden.
73 73  
74 -=== Deploy-Action
76 +=== Deploy-Action ===
75 75  
76 76  Der Wert des Parameters //deploy-action// gibt an, was genau mit dem Plugin geschehen soll. Es gibt dabei die folgenden Möglichkeiten:
77 77  
78 78  ; save
79 79  : Überträgt das angegebene Plugin auf das FORMCYCLE-System. Es muss hierbei eine JAR-Datei übertragen werden. Falls das Plugin noch nicht existiert (und der Parameter //disallow-install// nicht gesetzt ist), wird das Plugin neu installiert und ist dann aktiviert. Andernfalls, falls das Plugin bereits existiert, wird es aktualisiert, dabei bleibt das Plugin aktiviert oder deaktiviert.
82 +
80 80  (((
81 81  {{code language="bash"}}
85 +# Installiert oder aktualisiert das Plugin mit dem Implementation-Title com.example:plugin
82 82   curl -X POST \
83 - # These options are required
84 84   -F deploy-action=save \
85 85   -F token=admin \
86 86   -F plugin-ident=manifest \
... ... @@ -89,12 +89,14 @@
89 89   "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
90 90  {{/code}}
91 91  )))
95 +
92 92  ; delete
93 93  : Löscht das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
98 +
94 94  (((
95 95  {{code language="bash"}}
101 +# Löscht das Plugin mit dem Implementation-Title com.example:plugin
96 96   curl -X POST \
97 - # These options are required
98 98   -F deploy-action=delete \
99 99   -F token=admin \
100 100   -F plugin-ident=manifest \
... ... @@ -102,12 +102,14 @@
102 102   "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
103 103  {{/code}}
104 104  )))
110 +
105 105  ; activate
106 -: Aktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
112 +: Aktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Ist das Plugin bereits aktiviert, wird nicht getan und ein Erfolg zurückgegeben. Beispiel:
113 +
107 107  (((
108 108  {{code language="bash"}}
116 +# Aktiviert das Plugin mit dem Implementation-Title com.example:plugin
109 109   curl -X POST \
110 - # These options are required
111 111   -F deploy-action=activate \
112 112   -F token=admin \
113 113   -F plugin-ident=manifest \
... ... @@ -115,12 +115,14 @@
115 115   "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
116 116  {{/code}}
117 117  )))
125 +
118 118  ; deactivate
119 -: Deaktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
127 +: Deaktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Ist das Plugin bereits deaktiviert, wird nicht getan und ein Erfolg zurückgegeben. Beispiel:
128 +
120 120  (((
121 121  {{code language="bash"}}
131 +# Deaktiviert oder aktualisiert das Plugin mit dem Implementation-Title com.example:plugin
122 122   curl -X POST \
123 - # These options are required
124 124   -F deploy-action=deactivate \
125 125   -F token=admin \
126 126   -F plugin-ident=manifest \
... ... @@ -128,9 +128,10 @@
128 128   "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
129 129  {{/code}}
130 130  )))
140 +
131 131  ; update-properties
132 132  : Aktualisiert die Eigenschaften des angegebenen Plugins. Es darf hierbei keine JAR-Datei übertragen werden. Entweder die Eigenschaft //clear-properties// oder //property// sollte gesetzt sein. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
133 - (((
143 +(((
134 134  {{code language="bash"}}
135 135  # Löscht alle vorhandenen Plugin-Eigenschaften und setzt dann die Eigenschaft "foo" auf den Wert "bar"
136 136   curl -X POST \
... ... @@ -141,10 +141,160 @@
141 141   -F clear-properties=false \
142 142   -F property=foo=bar \
143 143   "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
144 -{{/code}})))
154 +{{/code}}
155 +)))
145 145  
146 -== Response
157 +== Response ==
147 147  
159 +Das Deploy-Plugin liefert einen Statuscode und ein JSON-Objekt mit den Details zurück. Der Status-Code ist 2xx, falls das Deploy-Plugin erfolgreich ausgeführt wurde.
148 148  
161 +Das JSON-Objekt hat dabei [[die folgende Struktur>>https://json-schema.org/]]:
149 149  
163 +{{code language="json"}}
164 +{
165 + "$schema": "http://json-schema.org/schema",
166 + "description": "Represents the response of the deploy plugin servlet.",
167 + "required": [
168 + "success",
169 + "statusCode",
170 + "details",
171 + "message",
172 + "requestParameters"
173 + ],
174 + "properties": {
175 + "success": {
176 + "type": "boolean",
177 + "title": "Success status",
178 + "description": "true if the deploy plugin servlet was executed successfully, or false otherwise"
179 + },
180 + "statusCode": {
181 + "type": "number",
182 + "title": "HTTP status code",
183 + "description": "The status code of the HTTP request that contains this response."
184 + },
185 + "details": {
186 + "type": "object",
187 + "title": "Result details",
188 + "description": "Detailed information about the plugin processed by the deploy plugin servlet.",
189 + "oneOf": [
190 + {
191 + "description": "If the deploy plugin servlet was successful, details about the successfully executed action.",
192 + "required": [
193 + "id",
194 + "uuid",
195 + "name",
196 + "active",
197 + "message"
198 + ],
199 + "properties": {
200 + "id": {
201 + "type": "number",
202 + "title": "Plugin ID",
203 + "description": "The database ID of the processed plugin."
204 + },
205 + "uuid": {
206 + "type": "string",
207 + "title": "Plugin UUID",
208 + "description": "The UUID of the processed plugin."
209 + },
210 + "name": {
211 + "type": "string",
212 + "title": "Plugin name",
213 + "description": "The name of the processed plugin, i.e. the file name of the plugin JAR file."
214 + },
215 + "active": {
216 + "type": "boolean",
217 + "title": "Plugin activation status",
218 + "description": "true if the plugin is now active, false if it is now inactive."
219 + },
220 + "message": {
221 + "type": "string",
222 + "title": "Result message",
223 + "description": "Human-readable message describing the performed action."
224 + }
225 + }
226 + },
227 + {
228 + "required": [
229 + "exceptionType",
230 + "exceptionMessage"
231 + ],
232 + "description": "If the deploy plugin servlet was unsuccessful, details about the error that occurred.",
233 + "properties": {
234 + "exceptionType": {
235 + "type": "string",
236 + "title": "Exception type",
237 + "description": "The type of the error that occurred, a fully-classified name of the Java exception class."
238 + },
239 + "exceptionMessage": {
240 + "type": "string",
241 + "title": "Exception message",
242 + "description": "The human-readable message of the error that occurred."
243 + }
244 + }
245 + }
246 + ]
247 + },
248 + "message": {
249 + "type": "string",
250 + "title": "Result message",
251 + "description": "A human-readable message that describes this result."
252 + },
253 + "requestParameters": {
254 + "type": "object",
255 + "title": "Request parameters",
256 + "description": "The parameters of the request that triggered this response."
257 + }
258 + }
259 +}
260 +{{/code}}
261 +
262 +Beispiel für die Antwort beim Aktualisieren eines Plugins:
263 +
264 +{{code language="json"}}
265 +{
266 + "success": true,
267 + "requestParameters": {
268 + "plugin-ident": ["manifest"],
269 + "name": ["deploy-plugin"],
270 + "client-id": ["1"],
271 + "deploy-action": ["save"],
272 + "plugin-identifier": ["Implementation-Title=com.example:plugin"],
273 + "token": ["admin"]
274 + },
275 + "details": {
276 + "name": "my-plugin.jar",
277 + "active": true,
278 + "id": 203,
279 + "message": "Plugin saved successfully.",
280 + "uuid": "2fe3e1ba-cb32-434e-9f59-4422f8dabcad"
281 + },
282 + "message": "Plugin saved successfully.",
283 + "statusCode": 200
284 +}
285 +{{/code}}
286 +
287 +Beispiel für die Antwort beim Löschen, falls das angegebene Plugin nicht gefunden wurde:
288 +
289 +{{code language="json"}}
290 +{
291 + "success": false,
292 + "requestParameters": {
293 + "plugin-ident": ["manifest"],
294 + "name": ["deploy-plugin"],
295 + "client-id": ["1"],
296 + "deploy-action": ["delete"],
297 + "plugin-identifier": ["Implementation-Title=com.example:plugin"],
298 + "token": ["admin"]
299 + },
300 + "details": {
301 + "exceptionType": "java.lang.IllegalArgumentException",
302 + "exceptionMessage": "Deploy action 'delete' requires an existing pluign, but none was found."
303 + },
304 + "message": "class java.lang.IllegalArgumentException: Deploy action 'delete' requires an existing pluign, but none was found.",
305 + "statusCode": 404
306 +}
307 +{{/code}}
308 +
309 +
150 150  == Beispiel für Maven ==

Navigation

Copyright 2000-2025