001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.config;
018
019
020import java.util.*;
021
022import org.apache.juneau.marshall.serializer.*;
023import static org.apache.juneau.commons.utils.Shorts.*;
024
025/**
026 * A fluent builder for adding or updating a single {@link Config} entry.
027 *
028 * <p>
029 * This is an ergonomic, self-documenting alternative to the multi-argument
030 * {@link Config#set(String, Object, Serializer, String, List)} overload.  That overload packs several distinct
031 * "leave-unchanged versus clear" sentinel conventions into one call (a <jk>null</jk> comment leaves the existing comment
032 * untouched while a blank comment clears it; a <jk>null</jk> pre-lines list leaves the existing pre-lines untouched while
033 * an empty list clears them).  This builder replaces those sentinels with explicit methods:
034 * <ul>
035 *    <li><b>Not calling</b> a facet method leaves that facet untouched (no sentinel needed).
036 *    <li>An explicit setter ({@link #comment(String)}, {@link #preLines(List)}, {@link #serializer(Serializer)}) sets that facet.
037 *    <li>An explicit clear ({@link #clearComment()}, {@link #clearPreLines()}) intentionally clears that facet rather than
038 *       relying on a magic blank string or empty list.
039 * </ul>
040 *
041 * <p>
042 * The write is performed by the terminal {@link #set(Object)} or {@link #set()} method.  The result is identical to the
043 * equivalent {@link Config#set(String, Object, Serializer, String, List)} call.
044 *
045 * <h2 class='section'>Example:</h2>
046 * <p class='bjava'>
047 *    <jc>// Add an entry with a comment and pre-lines.</jc>
048 *    <jv>config</jv>.entry(<js>"MySection/myKey"</js>)
049 *       .comment(<js>"My comment"</js>)
050 *       .preLines(List.<jsm>of</jsm>(<js>"# A pre-line"</js>))
051 *       .set(<js>"My value"</js>);
052 *
053 *    <jc>// Update only the comment on an existing entry, leaving the value and pre-lines untouched.</jc>
054 *    <jv>config</jv>.entry(<js>"MySection/myKey"</js>)
055 *       .comment(<js>"Updated comment"</js>)
056 *       .set();
057 *
058 *    <jc>// Clear the comment on an existing entry.</jc>
059 *    <jv>config</jv>.entry(<js>"MySection/myKey"</js>)
060 *       .clearComment()
061 *       .set();
062 * </p>
063 *
064 * <h2 class='section'>Notes:</h2><ul>
065 *    <li class='note'>This builder is not thread safe and is intended to be used and discarded within a single statement.
066 * </ul>
067 *
068 * <h2 class='section'>See Also:</h2><ul>
069 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauConfig">juneau-config</a>
070 * </ul>
071 */
072public class EntryBuilder {
073
074   private final Config config;
075   private final String key;
076
077   private Object value;
078   private Serializer serializer;
079   private String comment;
080   private List<String> preLines;
081
082   /**
083    * Constructor.
084    *
085    * @param config The config that the entry belongs to.
086    * @param key
087    *    The key of the entry to add or update.
088    *    <br>Must not be <jk>null</jk>.
089    */
090   protected EntryBuilder(Config config, String key) {
091      reqnn("key", key);
092      this.config = config;
093      this.key = key;
094   }
095
096   /**
097    * Specifies the value to store on the entry.
098    *
099    * <p>
100    * Equivalent to passing the value to the terminal {@link #set(Object)} method.
101    *
102    * @param value
103    *    The new value POJO.
104    *    <br>Serialized to a string using the registered (or {@link #serializer(Serializer) specified}) serializer.
105    * @return This object.
106    */
107   public EntryBuilder value(Object value) {
108      this.value = value;
109      return this;
110   }
111
112   /**
113    * Specifies the serializer to use to serialize the value.
114    *
115    * <p>
116    * If not called, the serializer registered on the config is used.
117    *
118    * @param value The serializer to use for serializing the value.
119    * @return This object.
120    */
121   public EntryBuilder serializer(Serializer value) {
122      this.serializer = value;
123      return this;
124   }
125
126   /**
127    * Specifies the same-line comment to add to the entry.
128    *
129    * <p>
130    * If not called, the comment on any existing entry is left untouched.
131    * <br>Use {@link #clearComment()} to explicitly remove an existing comment.
132    *
133    * @param value The same-line comment to add to the entry.  Must not be <jk>null</jk> (use {@link #clearComment()} instead).
134    * @return This object.
135    */
136   public EntryBuilder comment(String value) {
137      reqnn("value", value);
138      this.comment = value;
139      return this;
140   }
141
142   /**
143    * Explicitly clears the same-line comment on the entry.
144    *
145    * @return This object.
146    */
147   public EntryBuilder clearComment() {
148      this.comment = "";
149      return this;
150   }
151
152   /**
153    * Specifies the comment or blank lines to add before the entry.
154    *
155    * <p>
156    * If not called, the pre-lines on any existing entry are left untouched.
157    * <br>Use {@link #clearPreLines()} to explicitly remove existing pre-lines.
158    *
159    * @param value The comment or blank lines to add before the entry.  Must not be <jk>null</jk> (use {@link #clearPreLines()} instead).
160    * @return This object.
161    */
162   public EntryBuilder preLines(List<String> value) {
163      reqnn("value", value);
164      this.preLines = value;
165      return this;
166   }
167
168   /**
169    * Explicitly clears the pre-lines on the entry.
170    *
171    * @return This object.
172    */
173   public EntryBuilder clearPreLines() {
174      this.preLines = Collections.emptyList();
175      return this;
176   }
177
178   /**
179    * Adds or updates the entry using the value specified via {@link #value(Object)}.
180    *
181    * @return The config that this builder belongs to.
182    * @throws SerializeException
183    *    If serializer could not serialize the value or if a serializer is not registered with this config file.
184    * @throws UnsupportedOperationException If configuration is read only.
185    */
186   public Config set() throws SerializeException {
187      return config.set(key, value, serializer, comment, preLines);
188   }
189
190   /**
191    * Adds or updates the entry using the specified value.
192    *
193    * @param value
194    *    The new value POJO.
195    *    <br>Serialized to a string using the registered (or {@link #serializer(Serializer) specified}) serializer.
196    * @return The config that this builder belongs to.
197    * @throws SerializeException
198    *    If serializer could not serialize the value or if a serializer is not registered with this config file.
199    * @throws UnsupportedOperationException If configuration is read only.
200    */
201   public Config set(Object value) throws SerializeException {
202      this.value = value;
203      return set();
204   }
205}