001package gov.nist.secauto.oscal.lib.model; 002 003import gov.nist.secauto.metaschema.core.datatype.adapter.StringAdapter; 004import gov.nist.secauto.metaschema.core.datatype.adapter.UuidAdapter; 005import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine; 006import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLineAdapter; 007import gov.nist.secauto.metaschema.core.model.IBoundObject; 008import gov.nist.secauto.metaschema.core.model.IMetaschemaData; 009import gov.nist.secauto.metaschema.core.model.JsonGroupAsBehavior; 010import gov.nist.secauto.metaschema.core.model.constraint.IConstraint; 011import gov.nist.secauto.metaschema.core.util.ObjectUtils; 012import gov.nist.secauto.metaschema.databind.model.annotations.BoundAssembly; 013import gov.nist.secauto.metaschema.databind.model.annotations.BoundField; 014import gov.nist.secauto.metaschema.databind.model.annotations.BoundFlag; 015import gov.nist.secauto.metaschema.databind.model.annotations.Expect; 016import gov.nist.secauto.metaschema.databind.model.annotations.GroupAs; 017import gov.nist.secauto.metaschema.databind.model.annotations.MetaschemaAssembly; 018import gov.nist.secauto.metaschema.databind.model.annotations.ValueConstraints; 019import java.lang.Override; 020import java.lang.String; 021import java.util.LinkedList; 022import java.util.List; 023import java.util.UUID; 024import org.apache.commons.lang3.builder.ReflectionToStringBuilder; 025import org.apache.commons.lang3.builder.ToStringStyle; 026 027/** 028 * Information about the protocol used to provide a service. 029 */ 030@MetaschemaAssembly( 031 formalName = "Service Protocol Information", 032 description = "Information about the protocol used to provide a service.", 033 name = "protocol", 034 moduleClass = OscalImplementationCommonModule.class, 035 valueConstraints = @ValueConstraints(expect = @Expect(level = IConstraint.Level.WARNING, test = "@uuid", message = "It is a best practice to provide a UUID.")) 036) 037public class Protocol implements IBoundObject { 038 private final IMetaschemaData __metaschemaData; 039 040 /** 041 * "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." 042 */ 043 @BoundFlag( 044 formalName = "Service Protocol Information Universally Unique Identifier", 045 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.", 046 name = "uuid", 047 typeAdapter = UuidAdapter.class 048 ) 049 private UUID _uuid; 050 051 /** 052 * "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>." 053 */ 054 @BoundFlag( 055 formalName = "Protocol Name", 056 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).", 057 name = "name", 058 required = true, 059 typeAdapter = StringAdapter.class, 060 remarks = "The short name of the protocol (e.g., https)." 061 ) 062 private String _name; 063 064 @BoundField( 065 formalName = "Protocol Title", 066 description = "A human readable name for the protocol (e.g., Transport Layer Security).", 067 useName = "title", 068 typeAdapter = MarkupLineAdapter.class 069 ) 070 private MarkupLine _title; 071 072 @BoundAssembly( 073 formalName = "Port Range", 074 description = "Where applicable this is the IPv4 port range on which the service operates.", 075 useName = "port-range", 076 maxOccurs = -1, 077 groupAs = @GroupAs(name = "port-ranges", inJson = JsonGroupAsBehavior.LIST) 078 ) 079 private List<PortRange> _portRanges; 080 081 public Protocol() { 082 this(null); 083 } 084 085 public Protocol(IMetaschemaData data) { 086 this.__metaschemaData = data; 087 } 088 089 @Override 090 public IMetaschemaData getMetaschemaData() { 091 return __metaschemaData; 092 } 093 094 public UUID getUuid() { 095 return _uuid; 096 } 097 098 public void setUuid(UUID value) { 099 _uuid = value; 100 } 101 102 public String getName() { 103 return _name; 104 } 105 106 public void setName(String value) { 107 _name = value; 108 } 109 110 public MarkupLine getTitle() { 111 return _title; 112 } 113 114 public void setTitle(MarkupLine value) { 115 _title = value; 116 } 117 118 public List<PortRange> getPortRanges() { 119 return _portRanges; 120 } 121 122 public void setPortRanges(List<PortRange> value) { 123 _portRanges = value; 124 } 125 126 /** 127 * Add a new {@link PortRange} item to the underlying collection. 128 * @param item the item to add 129 * @return {@code true} 130 */ 131 public boolean addPortRange(PortRange item) { 132 PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null"); 133 if (_portRanges == null) { 134 _portRanges = new LinkedList<>(); 135 } 136 return _portRanges.add(value); 137 } 138 139 /** 140 * Remove the first matching {@link PortRange} item from the underlying collection. 141 * @param item the item to remove 142 * @return {@code true} if the item was removed or {@code false} otherwise 143 */ 144 public boolean removePortRange(PortRange item) { 145 PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null"); 146 return _portRanges != null && _portRanges.remove(value); 147 } 148 149 @Override 150 public String toString() { 151 return new ReflectionToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE).toString(); 152 } 153}