1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.execute.api;
23
24 import org.opencastproject.job.api.Job;
25 import org.opencastproject.mediapackage.MediaPackage;
26 import org.opencastproject.mediapackage.MediaPackageElement;
27
28 /**
29 * API for a service that runs CLI commands with MediaPackage elements as arguments
30 */
31
32 public interface ExecuteService {
33
34 /** Receipt type */
35 String JOB_TYPE = "org.opencastproject.execute";
36
37 /** Placeholder to be replaced by the actual track location in the command line */
38 String INPUT_FILE_PATTERN = "#{in}";
39
40 /** Placeholder to be replaced by the actual track location in the command line */
41 String OUTPUT_FILE_PATTERN = "#{out}";
42
43 /** Placeholder to be replaced by the actual organization id in the command line */
44 String ORG_ID_PATTERN = "#{org_id}";
45
46 /** Placeholder to be replaced by the actual mediapackage id in the command line */
47 String MP_ID_PATTERN = "#{id}";
48
49 /** The subdirectory of the REST endpoint for this service */
50 String ENDPOINT_NAME = "execute";
51
52 /** Name of the form parameter in the REST endpoints that contains the name of the command */
53 String EXEC_FORM_PARAM = "exec";
54
55 /** Name of the form parameter in the REST endpoints that contains the command arguments */
56 String PARAMS_FORM_PARAM = "params";
57
58 /** Name of the form parameter in the REST endpoints that contains the load estimate */
59 String LOAD_FORM_PARAM = "load";
60
61 /** Name of the form parameter in the REST endpoints that contains the serialized input element */
62 String INPUT_ELEM_FORM_PARAM = "inputElement";
63
64 /** Name of the form parameter in the REST endpoints that contains the serialized input element */
65 String INPUT_MP_FORM_PARAM = "inputMediaPackage";
66
67 /** Name of the form parameter in the REST endpoints that contains the name of the file generated by the command */
68 String OUTPUT_NAME_FORM_PARAMETER = "outputFilename";
69
70 /** Name of the form parameter in the REST endpoints that contains the element type of the generated file */
71 String TYPE_FORM_PARAMETER = "expectedType";
72
73 /** The collection for the executor files */
74 String COLLECTION = "executor";
75
76 /**
77 * Execute the operation specified by {@code exec} with the argument string indicated by {@code args}. This method may
78 * create an output file with the name {@code outFileName} and a
79 * {@link org.opencastproject.mediapackage.MediaPackageElement} will be created with the
80 * {@link org.opencastproject.mediapackage.MediaPackageElement.Type} indicated by the argument {@code type}.
81 *
82 * @param exec
83 * The command to be executed by this method
84 * @param args
85 * A string containing the argument list for this command. The special argument {@value #INPUT_FILE_PATTERN}
86 * will be substituted by the location of the resource represented by the {@code inElement} parameter, and
87 * {@value #OUTPUT_FILE_PATTERN} by the file name indicated in {@code outFileName}.
88 * @param inElement
89 * An {@link org.opencastproject.mediapackage.MediaPackageElement} object to be used as an input to the
90 * command
91 * @param outFileName
92 * The name of the file the command may possibly create.
93 * @param type
94 * The {@link org.opencastproject.mediapackage.MediaPackageElement.Type} of the {@code MediaPackageElement}
95 * created by this command.
96 * @param load
97 * A floating point estimate of the load imposed on the node by executing the command
98 * @return A {@link org.opencastproject.job.api.Job} representing the execution of the command. After a successful
99 * execution, the {link @Job} payload will contain a serialized mediapackage element.
100 * @throws ExecuteException
101 * if this method fails to create the {@code Job} correctly
102 */
103 Job execute(String exec, String args, MediaPackageElement inElement, String outFileName,
104 MediaPackageElement.Type type, float load) throws ExecuteException;
105
106 /**
107 * Execute the operation specified by {@code exec} with the argument string indicated by {@code args}. This method
108 * accepts a {@link org.opencastproject.mediapackage.MediaPackage} as an argument, and elements within that
109 * MediaPackage may be referenced in the argument list by using certain placeholders.
110 *
111 * @param exec
112 * The command to be executed by this method
113 * @param args
114 * A string containing the argument list for this command. Some special placeholders are allowed, that will
115 * be converted into the actual locations of elements in the supplied MediaPackage
116 * @param mp
117 * The {@link org.opencastproject.mediapackage.MediaPackage} containing {@code MediaPackageElements} that
118 * will be used as inputs of the command
119 * @param outFileName
120 * The name of the file the command may possibly create.
121 * @param type
122 * The {@link org.opencastproject.mediapackage.MediaPackageElement.Type} of the {@code MediaPackageElement}
123 * created by this command.
124 * @param load
125 * A floating point estimate of the load imposed on the node by executing the command
126 * @return A {@link org.opencastproject.job.api.Job} representing the execution of the command. After a successful
127 * execution, the {link @Job} payload will contain a serialized mediapackage element.
128 * @throws ExecuteException
129 * if this method fails to create the {@code Job} correctly
130 */
131 Job execute(String exec, String args, MediaPackage mp, String outFileName, MediaPackageElement.Type type, float load)
132 throws ExecuteException;
133
134 }