1   /* Copyright 2002-2026 CS GROUP
2    * Licensed to CS GROUP (CS) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * CS licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *   http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.orekit.files.ccsds.section;
18  
19  import java.util.ArrayList;
20  import java.util.Collections;
21  import java.util.List;
22  
23  import org.orekit.errors.OrekitException;
24  import org.orekit.errors.OrekitMessages;
25  
26  /** Container for comments in various CCSDS messages.
27   * <p>
28   * CCSDS files accept comments only at the beginning of sections.
29   * Once header/metadata/data content has started, comments in the
30   * corresponding section are refused.
31   * </p>
32   * @author Luc Maisonobe
33   * @since 11.0
34   */
35  public class CommentsContainer implements Section {
36  
37      /** Comments, as one line per string. */
38      private List<String> comments;
39  
40      /** Indicator for accepting comments. */
41      private boolean acceptComments;
42  
43      /** Create a new meta-data.
44       */
45      public CommentsContainer() {
46          comments       = new ArrayList<>();
47          acceptComments = true;
48      }
49  
50      /** Complain if a field is negative.
51       * @param field field to check
52       * @param key key associated with the field
53       */
54      public void checkNotNegative(final int field, final String key) {
55          if (field < 0) {
56              throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY, key);
57          }
58      }
59  
60      /** Complain if a field is NaN.
61       * @param field field to check
62       * @param key key associated with the field
63       */
64      public void checkNotNaN(final double field, final String key) {
65          if (Double.isNaN(field)) {
66              throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY, key);
67          }
68      }
69  
70      /** Complain if a field is null.
71       * @param field field to check
72       * @param key key associated with the field
73       */
74      public void checkNotNull(final Object field, final String key) {
75          if (field == null) {
76              throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY, key);
77          }
78      }
79  
80      /** Complain if a field is null.
81       * @param field field to check
82       * @param key key associated with the field
83       */
84      public void checkNotEmpty(final List<?> field, final String key) {
85          if (field.isEmpty()) {
86              throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY, key);
87          }
88      }
89  
90      /** Complain if a key is not allowed.
91       * @param version format version
92       * @param field field to check
93       * @param key key associated with the field
94       * @param minVersion version at which key started to be allowed
95       * @param maxVersion version at which key started to be forbidden
96       */
97      public void checkAllowed(final double version, final Object field, final String key,
98                               final double minVersion, final double maxVersion) {
99          if (field != null && (version < minVersion || version >= maxVersion)) {
100             throw new OrekitException(OrekitMessages.CCSDS_KEYWORD_NOT_ALLOWED_IN_VERSION,
101                                       key, version);
102         }
103     }
104 
105     /** {@inheritDoc} */
106     @Override
107     public void validate(final double version) {
108         // nothing to do here
109     }
110 
111     /** Get the comments.
112      * @return comments
113      */
114     public List<String> getComments() {
115         return Collections.unmodifiableList(comments);
116     }
117 
118     /** Set the comments. This removes all previous comments and replaces them with the new ones.
119      * @param comments List with new comments
120      */
121     public void setComments(final List<String> comments) {
122         this.comments = comments;
123     }
124 
125     /** Check if container is still accepting comments.
126      * <p>
127      * A container that still accept comments does not contain any other data.
128      * </p>
129      * @return true if container is still accepting comments
130      */
131     public boolean acceptComments() {
132         return acceptComments;
133     }
134 
135     /** Set flag to refuse further comments.
136      */
137     public void refuseFurtherComments() {
138         acceptComments = false;
139     }
140 
141     /**
142      * Add comment.
143      * <p>
144      * Comments are accepted only at start. Once
145      * other content is stored in the same section, comments are refused.
146      * </p>
147      * @param comment comment line
148      * @return true if comment was accepted
149      */
150     public boolean addComment(final String comment) {
151         if (acceptComments) {
152             comments.add(comment);
153             return true;
154         } else {
155             return false;
156         }
157     }
158 }