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