001// Generated from: ../../../../../../../../oscal/src/metaschema/oscal_implementation-common_metaschema.xml 002// Do not edit - changes will be lost when regenerated. 003package dev.metaschema.oscal.lib.model; 004 005import dev.metaschema.core.datatype.adapter.StringAdapter; 006import dev.metaschema.core.datatype.adapter.UuidAdapter; 007import dev.metaschema.core.datatype.markup.MarkupLine; 008import dev.metaschema.core.datatype.markup.MarkupLineAdapter; 009import dev.metaschema.core.model.IBoundObject; 010import dev.metaschema.core.model.IMetaschemaData; 011import dev.metaschema.core.model.JsonGroupAsBehavior; 012import dev.metaschema.core.model.constraint.IConstraint; 013import dev.metaschema.core.util.ObjectUtils; 014import dev.metaschema.databind.model.annotations.BoundAssembly; 015import dev.metaschema.databind.model.annotations.BoundField; 016import dev.metaschema.databind.model.annotations.BoundFlag; 017import dev.metaschema.databind.model.annotations.Expect; 018import dev.metaschema.databind.model.annotations.GroupAs; 019import dev.metaschema.databind.model.annotations.MetaschemaAssembly; 020import dev.metaschema.databind.model.annotations.ValueConstraints; 021import edu.umd.cs.findbugs.annotations.NonNull; 022import edu.umd.cs.findbugs.annotations.Nullable; 023import java.util.LinkedList; 024import java.util.List; 025import java.util.UUID; 026import org.apache.commons.lang3.builder.ReflectionToStringBuilder; 027import org.apache.commons.lang3.builder.ToStringStyle; 028 029/** 030 * Information about the protocol used to provide a service. 031 */ 032@MetaschemaAssembly( 033 formalName = "Service Protocol Information", 034 description = "Information about the protocol used to provide a service.", 035 name = "protocol", 036 moduleClass = OscalImplementationCommonModule.class, 037 valueConstraints = @ValueConstraints(expect = @Expect(id = "oscal-component-protocol-uuid", level = IConstraint.Level.WARNING, test = "@uuid", message = "It is a best practice to provide a UUID.")) 038) 039public class Protocol implements IBoundObject { 040 private final IMetaschemaData __metaschemaData; 041 042 /** 043 * A <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this service protocol information elsewhere in <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>service protocol</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document. 044 */ 045 @BoundFlag( 046 formalName = "Service Protocol Information Universally Unique Identifier", 047 description = "A [machine-oriented](https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented), [globally unique](https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique) identifier with [cross-instance](https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance) scope that can be used to reference this service protocol information elsewhere in [this or other OSCAL instances](https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope). The locally defined *UUID* of the `service protocol` can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned [per-subject](https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency), which means it should be consistently used to identify the same subject across revisions of the document.", 048 name = "uuid", 049 typeAdapter = UuidAdapter.class 050 ) 051 private UUID _uuid; 052 053 /** 054 * The common name of the protocol, which should be the appropriate "service name" from the <a href="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml">IANA Service Name and Transport Protocol Port Number Registry</a>. 055 */ 056 @BoundFlag( 057 formalName = "Protocol Name", 058 description = "The common name of the protocol, which should be the appropriate \"service name\" from the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml).", 059 name = "name", 060 typeAdapter = StringAdapter.class, 061 remarks = "The short name of the protocol (e.g., https)." 062 ) 063 private String _name; 064 065 /** 066 * A human readable name for the protocol (e.g., Transport Layer Security). 067 */ 068 @BoundField( 069 formalName = "Protocol Title", 070 description = "A human readable name for the protocol (e.g., Transport Layer Security).", 071 useName = "title", 072 typeAdapter = MarkupLineAdapter.class 073 ) 074 private MarkupLine _title; 075 076 /** 077 * Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses. 078 */ 079 @BoundAssembly( 080 formalName = "Port Range", 081 description = "Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.", 082 useName = "port-range", 083 maxOccurs = -1, 084 groupAs = @GroupAs(name = "port-ranges", inJson = JsonGroupAsBehavior.LIST) 085 ) 086 private List<PortRange> _portRanges; 087 088 /** 089 * Constructs a new {@code dev.metaschema.oscal.lib.model.Protocol} instance with no metadata. 090 */ 091 public Protocol() { 092 this(null); 093 } 094 095 /** 096 * Constructs a new {@code dev.metaschema.oscal.lib.model.Protocol} instance with the specified metadata. 097 * 098 * @param data 099 * the metaschema data, or {@code null} if none 100 */ 101 public Protocol(IMetaschemaData data) { 102 this.__metaschemaData = data; 103 } 104 105 @Override 106 public IMetaschemaData getMetaschemaData() { 107 return __metaschemaData; 108 } 109 110 /** 111 * Get the "{@literal Service Protocol Information Universally Unique Identifier}". 112 * 113 * <p> 114 * A <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this service protocol information elsewhere in <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>service protocol</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document. 115 * 116 * @return the uuid value, or {@code null} if not set 117 */ 118 @Nullable 119 public UUID getUuid() { 120 return _uuid; 121 } 122 123 /** 124 * Set the "{@literal Service Protocol Information Universally Unique Identifier}". 125 * 126 * <p> 127 * A <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this service protocol information elsewhere in <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>service protocol</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href="https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document. 128 * 129 * @param value 130 * the uuid value to set, or {@code null} to clear 131 */ 132 public void setUuid(@Nullable UUID value) { 133 _uuid = value; 134 } 135 136 /** 137 * Get the "{@literal Protocol Name}". 138 * 139 * <p> 140 * The common name of the protocol, which should be the appropriate "service name" from the <a href="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml">IANA Service Name and Transport Protocol Port Number Registry</a>. 141 * 142 * @return the name value, or {@code null} if not set 143 */ 144 @Nullable 145 public String getName() { 146 return _name; 147 } 148 149 /** 150 * Set the "{@literal Protocol Name}". 151 * 152 * <p> 153 * The common name of the protocol, which should be the appropriate "service name" from the <a href="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml">IANA Service Name and Transport Protocol Port Number Registry</a>. 154 * 155 * @param value 156 * the name value to set, or {@code null} to clear 157 */ 158 public void setName(@Nullable String value) { 159 _name = value; 160 } 161 162 /** 163 * Get the "{@literal Protocol Title}". 164 * 165 * <p> 166 * A human readable name for the protocol (e.g., Transport Layer Security). 167 * 168 * @return the title value, or {@code null} if not set 169 */ 170 @Nullable 171 public MarkupLine getTitle() { 172 return _title; 173 } 174 175 /** 176 * Set the "{@literal Protocol Title}". 177 * 178 * <p> 179 * A human readable name for the protocol (e.g., Transport Layer Security). 180 * 181 * @param value 182 * the title value to set, or {@code null} to clear 183 */ 184 public void setTitle(@Nullable MarkupLine value) { 185 _title = value; 186 } 187 188 /** 189 * Get the "{@literal Port Range}". 190 * 191 * <p> 192 * Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses. 193 * 194 * @return the port-range value 195 */ 196 @NonNull 197 public List<PortRange> getPortRanges() { 198 if (_portRanges == null) { 199 _portRanges = new LinkedList<>(); 200 } 201 return ObjectUtils.notNull(_portRanges); 202 } 203 204 /** 205 * Set the "{@literal Port Range}". 206 * 207 * <p> 208 * Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses. 209 * 210 * @param value 211 * the port-range value to set 212 */ 213 public void setPortRanges(@NonNull List<PortRange> value) { 214 _portRanges = value; 215 } 216 217 /** 218 * Add a new {@link PortRange} item to the underlying collection. 219 * @param item the item to add 220 * @return {@code true} 221 */ 222 public boolean addPortRange(PortRange item) { 223 PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null"); 224 if (_portRanges == null) { 225 _portRanges = new LinkedList<>(); 226 } 227 return _portRanges.add(value); 228 } 229 230 /** 231 * Remove the first matching {@link PortRange} item from the underlying collection. 232 * @param item the item to remove 233 * @return {@code true} if the item was removed or {@code false} otherwise 234 */ 235 public boolean removePortRange(PortRange item) { 236 PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null"); 237 return _portRanges != null && _portRanges.remove(value); 238 } 239 240 @Override 241 public String toString() { 242 return ObjectUtils.notNull(new ReflectionToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE).toString()); 243 } 244}