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}