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}