001package gov.nist.secauto.oscal.lib.model; 002 003import gov.nist.secauto.metaschema.binding.model.annotations.AllowedValue; 004import gov.nist.secauto.metaschema.binding.model.annotations.AllowedValues; 005import gov.nist.secauto.metaschema.binding.model.annotations.BoundAssembly; 006import gov.nist.secauto.metaschema.binding.model.annotations.BoundField; 007import gov.nist.secauto.metaschema.binding.model.annotations.BoundFieldValue; 008import gov.nist.secauto.metaschema.binding.model.annotations.BoundFlag; 009import gov.nist.secauto.metaschema.binding.model.annotations.Expect; 010import gov.nist.secauto.metaschema.binding.model.annotations.GroupAs; 011import gov.nist.secauto.metaschema.binding.model.annotations.MetaschemaAssembly; 012import gov.nist.secauto.metaschema.binding.model.annotations.ValueConstraints; 013import gov.nist.secauto.metaschema.model.common.JsonGroupAsBehavior; 014import gov.nist.secauto.metaschema.model.common.constraint.IConstraint; 015import gov.nist.secauto.metaschema.model.common.datatype.adapter.TokenAdapter; 016import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLine; 017import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLineAdapter; 018import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupMultiline; 019import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupMultilineAdapter; 020import gov.nist.secauto.metaschema.model.common.util.ObjectUtils; 021import gov.nist.secauto.oscal.lib.model.control.AbstractParameter; 022import java.lang.Override; 023import java.lang.String; 024import java.util.LinkedList; 025import java.util.List; 026import org.apache.commons.lang3.builder.MultilineRecursiveToStringStyle; 027import org.apache.commons.lang3.builder.ReflectionToStringBuilder; 028 029/** 030 * Parameters provide a mechanism for the dynamic assignment of value(s) in a control. 031 */ 032@MetaschemaAssembly( 033 formalName = "Parameter", 034 description = "Parameters provide a mechanism for the dynamic assignment of value(s) in a control.", 035 name = "parameter", 036 metaschema = OscalControlCommonMetaschema.class, 037 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" 038 + "\n" 039 + "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." 040) 041@ValueConstraints( 042 allowedValues = { 043 @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.")}), 044 @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.")) 045 }, 046 expect = @Expect(level = IConstraint.Level.ERROR, test = "not(exists(@depends-on))", message = "depends-on is deprecated") 047) 048public class Parameter extends AbstractParameter { 049 @BoundFlag( 050 formalName = "Parameter Identifier", 051 description = "A unique identifier for the parameter.", 052 useName = "id", 053 required = true, 054 typeAdapter = TokenAdapter.class 055 ) 056 private String _id; 057 058 @BoundFlag( 059 formalName = "Parameter Class", 060 description = "A textual label that provides a characterization of the type, purpose, use or scope of the parameter.", 061 useName = "class", 062 typeAdapter = TokenAdapter.class, 063 remarks = "A `class` can be used in validation rules to express extra constraints over named items of a specific `class` value." 064 ) 065 private String _clazz; 066 067 @BoundFlag( 068 formalName = "Depends on", 069 description = "**(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.", 070 useName = "depends-on", 071 typeAdapter = TokenAdapter.class 072 ) 073 private String _dependsOn; 074 075 @BoundAssembly( 076 formalName = "Property", 077 description = "An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.", 078 useName = "prop", 079 maxOccurs = -1 080 ) 081 @GroupAs( 082 name = "props", 083 inJson = JsonGroupAsBehavior.LIST 084 ) 085 private List<Property> _props; 086 087 @BoundAssembly( 088 formalName = "Link", 089 description = "A reference to a local or remote resource, that has a specific relation to the containing object.", 090 useName = "link", 091 maxOccurs = -1 092 ) 093 @GroupAs( 094 name = "links", 095 inJson = JsonGroupAsBehavior.LIST 096 ) 097 private List<Link> _links; 098 099 /** 100 * "A short, placeholder name for the parameter, which can be used as a substitute for a <code>value</code> if no value is assigned." 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 * "Describes the purpose and use of a parameter." 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 * Add a new {@link Property} item to the underlying collection. 222 * @param item the item to add 223 * @return {@code true} 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 * Remove the first matching {@link Property} item from the underlying collection. 235 * @param item the item to remove 236 * @return {@code true} if the item was removed or {@code false} otherwise 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 * Add a new {@link Link} item to the underlying collection. 253 * @param item the item to add 254 * @return {@code true} 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 * Remove the first matching {@link Link} item from the underlying collection. 266 * @param item the item to remove 267 * @return {@code true} if the item was removed or {@code false} otherwise 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 * Add a new {@link ParameterConstraint} item to the underlying collection. 300 * @param item the item to add 301 * @return {@code true} 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 * Remove the first matching {@link ParameterConstraint} item from the underlying collection. 313 * @param item the item to remove 314 * @return {@code true} if the item was removed or {@code false} otherwise 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 * Add a new {@link ParameterGuideline} item to the underlying collection. 331 * @param item the item to add 332 * @return {@code true} 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 * Remove the first matching {@link ParameterGuideline} item from the underlying collection. 344 * @param item the item to remove 345 * @return {@code true} if the item was removed or {@code false} otherwise 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 * Add a new {@link String} item to the underlying collection. 362 * @param item the item to add 363 * @return {@code true} 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 * Remove the first matching {@link String} item from the underlying collection. 375 * @param item the item to remove 376 * @return {@code true} if the item was removed or {@code false} otherwise 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}