1 package gov.nist.secauto.oscal.lib.model;
2
3 import gov.nist.secauto.metaschema.binding.model.annotations.AllowedValue;
4 import gov.nist.secauto.metaschema.binding.model.annotations.AllowedValues;
5 import gov.nist.secauto.metaschema.binding.model.annotations.BoundAssembly;
6 import gov.nist.secauto.metaschema.binding.model.annotations.BoundField;
7 import gov.nist.secauto.metaschema.binding.model.annotations.BoundFieldValue;
8 import gov.nist.secauto.metaschema.binding.model.annotations.BoundFlag;
9 import gov.nist.secauto.metaschema.binding.model.annotations.Expect;
10 import gov.nist.secauto.metaschema.binding.model.annotations.GroupAs;
11 import gov.nist.secauto.metaschema.binding.model.annotations.MetaschemaAssembly;
12 import gov.nist.secauto.metaschema.binding.model.annotations.ValueConstraints;
13 import gov.nist.secauto.metaschema.model.common.JsonGroupAsBehavior;
14 import gov.nist.secauto.metaschema.model.common.constraint.IConstraint;
15 import gov.nist.secauto.metaschema.model.common.datatype.adapter.TokenAdapter;
16 import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLine;
17 import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLineAdapter;
18 import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupMultiline;
19 import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupMultilineAdapter;
20 import gov.nist.secauto.metaschema.model.common.util.ObjectUtils;
21 import gov.nist.secauto.oscal.lib.model.control.AbstractParameter;
22 import java.lang.Override;
23 import java.lang.String;
24 import java.util.LinkedList;
25 import java.util.List;
26 import org.apache.commons.lang3.builder.MultilineRecursiveToStringStyle;
27 import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
28
29
30
31
32 @MetaschemaAssembly(
33 formalName = "Parameter",
34 description = "Parameters provide a mechanism for the dynamic assignment of value(s) in a control.",
35 name = "parameter",
36 metaschema = OscalControlCommonMetaschema.class,
37 remarks = "In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The `value` may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.\n"
38 + "\n"
39 + "A parameter can include a variety of metadata options that support the future solicitation of one or more values. A `label` provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The `desc` provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A `constraint` can be used to provide criteria for the allowed values. A `guideline` provides a recommendation for the use of a parameter."
40 )
41 @ValueConstraints(
42 allowedValues = {
43 @AllowedValues(level = IConstraint.Level.ERROR, target = "prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name", values = {@AllowedValue(value = "label", description = "A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases."), @AllowedValue(value = "sort-id", description = "An alternative identifier, whose value is easily sortable among other such values in the document."), @AllowedValue(value = "alt-identifier", description = "An alternate or aliased identifier for the parent context."), @AllowedValue(value = "alt-label", description = "An alternate to the value provided by the parameter's label. This will typically be qualified by a class.")}),
44 @AllowedValues(level = IConstraint.Level.ERROR, target = "prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name", values = @AllowedValue(value = "aggregates", description = "The parent parameter provides an aggregation of two or more other parameters, each described by this property."))
45 },
46 expect = @Expect(level = IConstraint.Level.ERROR, test = "not(exists(@depends-on))", message = "depends-on is deprecated")
47 )
48 public class Parameter extends AbstractParameter {
49 @BoundFlag(
50 formalName = "Parameter Identifier",
51 description = "A unique identifier for the parameter.",
52 useName = "id",
53 required = true,
54 typeAdapter = TokenAdapter.class
55 )
56 private String _id;
57
58 @BoundFlag(
59 formalName = "Parameter Class",
60 description = "A textual label that provides a characterization of the type, purpose, use or scope of the parameter.",
61 useName = "class",
62 typeAdapter = TokenAdapter.class,
63 remarks = "A `class` can be used in validation rules to express extra constraints over named items of a specific `class` value."
64 )
65 private String _clazz;
66
67 @BoundFlag(
68 formalName = "Depends on",
69 description = "**(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.",
70 useName = "depends-on",
71 typeAdapter = TokenAdapter.class
72 )
73 private String _dependsOn;
74
75 @BoundAssembly(
76 formalName = "Property",
77 description = "An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.",
78 useName = "prop",
79 maxOccurs = -1
80 )
81 @GroupAs(
82 name = "props",
83 inJson = JsonGroupAsBehavior.LIST
84 )
85 private List<Property> _props;
86
87 @BoundAssembly(
88 formalName = "Link",
89 description = "A reference to a local or remote resource, that has a specific relation to the containing object.",
90 useName = "link",
91 maxOccurs = -1
92 )
93 @GroupAs(
94 name = "links",
95 inJson = JsonGroupAsBehavior.LIST
96 )
97 private List<Link> _links;
98
99
100
101
102 @BoundField(
103 formalName = "Parameter Label",
104 description = "A short, placeholder name for the parameter, which can be used as a substitute for a `value` if no value is assigned.",
105 useName = "label",
106 remarks = "The label value is intended use when rendering a parameter in generated documentation or a user interface when a parameter is referenced. Note that labels are not required to be distinctive, which means that parameters within the same control may have the same label."
107 )
108 @BoundFieldValue(
109 typeAdapter = MarkupLineAdapter.class
110 )
111 private MarkupLine _label;
112
113
114
115
116 @BoundField(
117 formalName = "Parameter Usage Description",
118 description = "Describes the purpose and use of a parameter.",
119 useName = "usage"
120 )
121 @BoundFieldValue(
122 typeAdapter = MarkupMultilineAdapter.class
123 )
124 private MarkupMultiline _usage;
125
126 @BoundAssembly(
127 formalName = "Constraint",
128 description = "A formal or informal expression of a constraint or test.",
129 useName = "constraint",
130 maxOccurs = -1
131 )
132 @GroupAs(
133 name = "constraints",
134 inJson = JsonGroupAsBehavior.LIST
135 )
136 private List<ParameterConstraint> _constraints;
137
138 @BoundAssembly(
139 formalName = "Guideline",
140 description = "A prose statement that provides a recommendation for the use of a parameter.",
141 useName = "guideline",
142 maxOccurs = -1
143 )
144 @GroupAs(
145 name = "guidelines",
146 inJson = JsonGroupAsBehavior.LIST
147 )
148 private List<ParameterGuideline> _guidelines;
149
150 @BoundField(
151 formalName = "Parameter Value",
152 description = "A parameter value or set of values.",
153 useName = "value",
154 maxOccurs = -1,
155 remarks = "A set of values provided in a catalog can be redefined in OSCAL's `profile` or `system-security-plan` models."
156 )
157 @GroupAs(
158 name = "values",
159 inJson = JsonGroupAsBehavior.LIST
160 )
161 private List<String> _values;
162
163 @BoundAssembly(
164 formalName = "Selection",
165 description = "Presenting a choice among alternatives.",
166 useName = "select",
167 remarks = "The OSCAL parameter `value` construct can be used to prescribe a specific parameter value in a catalog or profile. In cases where a prescriptive value is not possible in a catalog or profile, it may be possible to constrain the set of possible values to a few options. Use of `select` in a parameter instead of `value` is a way of defining value options that **may** be set.\n"
168 + "\n"
169 + "A set of allowed parameter values expressed as a set of options which may be selected. These options constrain the permissible values that may be selected for the containing parameter. When the value assignment is made, such as in an OSCAL profile or system security plan, the actual selected value can be examined to determine if it matches one of the permissible choices for the parameter value.\n"
170 + "\n"
171 + "When the value of `how-many` is set to \"one-or-more\", multiple values may be assigned reflecting more than one choice."
172 )
173 private ParameterSelection _select;
174
175 @BoundField(
176 formalName = "Remarks",
177 description = "Additional commentary about the containing object.",
178 useName = "remarks"
179 )
180 @BoundFieldValue(
181 typeAdapter = MarkupMultilineAdapter.class
182 )
183 private MarkupMultiline _remarks;
184
185 public Parameter() {
186 }
187
188 public String getId() {
189 return _id;
190 }
191
192 public void setId(String value) {
193 _id = value;
194 }
195
196 public String getClazz() {
197 return _clazz;
198 }
199
200 public void setClazz(String value) {
201 _clazz = value;
202 }
203
204 public String getDependsOn() {
205 return _dependsOn;
206 }
207
208 public void setDependsOn(String value) {
209 _dependsOn = value;
210 }
211
212 public List<Property> getProps() {
213 return _props;
214 }
215
216 public void setProps(List<Property> value) {
217 _props = value;
218 }
219
220
221
222
223
224
225 public boolean addProp(Property item) {
226 Property value = ObjectUtils.requireNonNull(item,"item cannot be null");
227 if (_props == null) {
228 _props = new LinkedList<>();
229 }
230 return _props.add(value);
231 }
232
233
234
235
236
237
238 public boolean removeProp(Property item) {
239 Property value = ObjectUtils.requireNonNull(item,"item cannot be null");
240 return _props == null ? false : _props.remove(value);
241 }
242
243 public List<Link> getLinks() {
244 return _links;
245 }
246
247 public void setLinks(List<Link> value) {
248 _links = value;
249 }
250
251
252
253
254
255
256 public boolean addLink(Link item) {
257 Link value = ObjectUtils.requireNonNull(item,"item cannot be null");
258 if (_links == null) {
259 _links = new LinkedList<>();
260 }
261 return _links.add(value);
262 }
263
264
265
266
267
268
269 public boolean removeLink(Link item) {
270 Link value = ObjectUtils.requireNonNull(item,"item cannot be null");
271 return _links == null ? false : _links.remove(value);
272 }
273
274 public MarkupLine getLabel() {
275 return _label;
276 }
277
278 public void setLabel(MarkupLine value) {
279 _label = value;
280 }
281
282 public MarkupMultiline getUsage() {
283 return _usage;
284 }
285
286 public void setUsage(MarkupMultiline value) {
287 _usage = value;
288 }
289
290 public List<ParameterConstraint> getConstraints() {
291 return _constraints;
292 }
293
294 public void setConstraints(List<ParameterConstraint> value) {
295 _constraints = value;
296 }
297
298
299
300
301
302
303 public boolean addConstraint(ParameterConstraint item) {
304 ParameterConstraint value = ObjectUtils.requireNonNull(item,"item cannot be null");
305 if (_constraints == null) {
306 _constraints = new LinkedList<>();
307 }
308 return _constraints.add(value);
309 }
310
311
312
313
314
315
316 public boolean removeConstraint(ParameterConstraint item) {
317 ParameterConstraint value = ObjectUtils.requireNonNull(item,"item cannot be null");
318 return _constraints == null ? false : _constraints.remove(value);
319 }
320
321 public List<ParameterGuideline> getGuidelines() {
322 return _guidelines;
323 }
324
325 public void setGuidelines(List<ParameterGuideline> value) {
326 _guidelines = value;
327 }
328
329
330
331
332
333
334 public boolean addGuideline(ParameterGuideline item) {
335 ParameterGuideline value = ObjectUtils.requireNonNull(item,"item cannot be null");
336 if (_guidelines == null) {
337 _guidelines = new LinkedList<>();
338 }
339 return _guidelines.add(value);
340 }
341
342
343
344
345
346
347 public boolean removeGuideline(ParameterGuideline item) {
348 ParameterGuideline value = ObjectUtils.requireNonNull(item,"item cannot be null");
349 return _guidelines == null ? false : _guidelines.remove(value);
350 }
351
352 public List<String> getValues() {
353 return _values;
354 }
355
356 public void setValues(List<String> value) {
357 _values = value;
358 }
359
360
361
362
363
364
365 public boolean addValue(String item) {
366 String value = ObjectUtils.requireNonNull(item,"item cannot be null");
367 if (_values == null) {
368 _values = new LinkedList<>();
369 }
370 return _values.add(value);
371 }
372
373
374
375
376
377
378 public boolean removeValue(String item) {
379 String value = ObjectUtils.requireNonNull(item,"item cannot be null");
380 return _values == null ? false : _values.remove(value);
381 }
382
383 public ParameterSelection getSelect() {
384 return _select;
385 }
386
387 public void setSelect(ParameterSelection value) {
388 _select = value;
389 }
390
391 public MarkupMultiline getRemarks() {
392 return _remarks;
393 }
394
395 public void setRemarks(MarkupMultiline value) {
396 _remarks = value;
397 }
398
399 @Override
400 public String toString() {
401 return new ReflectionToStringBuilder(this, MultilineRecursiveToStringStyle.MULTI_LINE_STYLE).toString();
402 }
403 }