001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     bstefanescu
018 */
019package org.nuxeo.ecm.automation;
020
021import java.util.Arrays;
022
023import org.nuxeo.common.xmap.annotation.XNode;
024import org.nuxeo.common.xmap.annotation.XNodeList;
025import org.nuxeo.common.xmap.annotation.XObject;
026import org.nuxeo.ecm.automation.core.Constants;
027import org.nuxeo.ecm.automation.core.OperationChainContribution;
028import org.nuxeo.ecm.platform.forms.layout.api.WidgetDefinition;
029
030/**
031 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
032 * @author <a href="mailto:grenard@nuxeo.com">Guillaume Renard</a>
033 */
034public class OperationDocumentation implements Comparable<OperationDocumentation> {
035
036    public String id;
037
038    /**
039     * @since 7.1
040     */
041    public String[] aliases;
042
043    /**
044     * an array of size multiple of 2. Each pair in the array is the input and output type of a method.
045     */
046    public String[] signature;
047
048    public String category;
049
050    public String label;
051
052    public String requires;
053
054    public String since;
055
056    /**
057     * @since 5.9.1
058     */
059    public String deprecatedSince;
060
061    /**
062     * @since 5.9.1
063     */
064    public boolean addToStudio;
065
066    /**
067     * @since 5.9.1
068     */
069    public String implementationClass;
070
071    public String description;
072
073    public Param[] params;
074
075    public WidgetDefinition[] widgetDefinitions;
076
077    /**
078     * The operations listing in case of a chain.
079     */
080    public OperationChainContribution.Operation[] operations;
081
082    // optional URL indicating the relative path (relative to the automation
083    // service home)
084    // of the page where the operation is exposed
085    public String url;
086
087    /**
088     * Returns a simple copy of an {@link OperationDocumentation} for an alias.
089     * <p>
090     * Array fields of {@code od} are shallow copied.
091     *
092     * @since 9.1
093     */
094    public static OperationDocumentation copyForAlias(OperationDocumentation od, String alias) {
095        OperationDocumentation documentation = new OperationDocumentation(alias);
096        documentation.signature = od.signature;
097        documentation.category = od.category;
098        documentation.label = od.label;
099        documentation.requires = od.requires;
100        documentation.since = od.since;
101        documentation.deprecatedSince = od.deprecatedSince;
102        documentation.addToStudio = od.addToStudio;
103        documentation.implementationClass = od.implementationClass;
104        documentation.description = od.description;
105        documentation.params = od.params;
106        documentation.widgetDefinitions = od.widgetDefinitions;
107        return documentation;
108    }
109
110    public OperationDocumentation(String id) {
111        this.id = id;
112        url = id;
113    }
114
115    @XObject("param")
116    public static class Param implements Comparable<Param> {
117
118        @XNode("@name")
119        public String name;
120
121        @XNode("@description")
122        public String description;
123
124        @XNode("@type")
125        public String type; // the data type
126
127        // is this useful (?)
128        public String widget; // the widget type
129
130        // is this useful (?)
131        @XNodeList(value = "value", type = String[].class, componentType = String.class)
132        public String[] values; // the default values
133
134        // is this useful (?)
135        @XNode("@order")
136        public int order;
137
138        // is this useful (?)
139        @XNode("@required")
140        public boolean required;
141
142        public Param() {
143        }
144
145        public String getName() {
146            return name;
147        }
148
149        /**
150         * @since 5.7.3
151         */
152        public String getDescription() {
153            return description;
154        }
155
156        public String getType() {
157            return type;
158        }
159
160        public String getWidget() {
161            return widget;
162        }
163
164        public String[] getValues() {
165            return values;
166        }
167
168        public boolean isRequired() {
169            return required;
170        }
171
172        public int getOrder() {
173            return order;
174        }
175
176        @Override
177        public String toString() {
178            return name + " [" + type + "] " + (required ? "required" : "optional");
179        }
180
181        @Override
182        public int compareTo(Param o) {
183            if (order != 0 && o.order != 0) {
184                if (order < o.order) {
185                    return -1;
186                } else if (order > o.order) {
187                    return 1;
188                }
189            }
190            if (required && !o.required) {
191                return -1;
192            }
193            if (o.required && !required) {
194                return 1;
195            }
196            return name.compareTo(o.name);
197        }
198    }
199
200    @Override
201    public int compareTo(OperationDocumentation o) {
202        String s1 = label == null ? id : label;
203        String s2 = o.label == null ? o.id : o.label;
204        return s1.compareTo(s2);
205    }
206
207    public String getDescription() {
208        return description;
209    }
210
211    /**
212     * @since 5.9.1
213     */
214    public String getSince() {
215        return since;
216    }
217
218    /**
219     * @since 5.9.1
220     */
221    public String getDeprecatedSince() {
222        return deprecatedSince;
223    }
224
225    /**
226     * @since 5.9.1
227     */
228    public boolean isAddToStudio() {
229        return addToStudio;
230    }
231
232    /**
233     * @since 5.9.1
234     */
235    public String getImplementationClass() {
236        return implementationClass;
237    }
238
239    /**
240     * @since 5.9.4
241     */
242    public boolean isChain() {
243        return (id != null && id.startsWith(Constants.CHAIN_ID_PREFIX)) || Constants.CAT_CHAIN.equals(category);
244    }
245
246    public String[] getSignature() {
247        return signature;
248    }
249
250    public String getCategory() {
251        return category;
252    }
253
254    public String getId() {
255        return id;
256    }
257
258    public String getUrl() {
259        return url;
260    }
261
262    public String getLabel() {
263        return label;
264    }
265
266    public String getRequires() {
267        return requires;
268    }
269
270    public Param[] getParams() {
271        return params;
272    }
273
274    public String[] getAliases() {
275        return aliases;
276    }
277
278    public void setAliases(String[] aliases) {
279        this.aliases = aliases;
280    }
281
282    public OperationChainContribution.Operation[] getOperations() {
283        return operations;
284    }
285
286    @Override
287    public String toString() {
288        return category + " > " + label + " [" + id + ": " + Arrays.toString(signature) + "] (" + Arrays.toString(params) + ")\n"
289                + description;
290    }
291}