1 /*
2 * Copyright 2012-2025 CodeLibs Project and the Others.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13 * either express or implied. See the License for the specific language
14 * governing permissions and limitations under the License.
15 */
16 package org.codelibs.fess.entity;
17
18 import java.util.HashMap;
19 import java.util.Map;
20
21 /**
22 * Parameter container class for data store configurations and runtime parameters.
23 * This class provides a convenient wrapper around a Map to store and retrieve
24 * data store specific parameters with type-safe access methods.
25 *
26 * <p>The class uses a ParamMap internally which provides case format conversion
27 * between camelCase and snake_case parameter names for flexible parameter access.
28 * Parameters can be stored as any Object type and retrieved with type conversion
29 * support for common types like String.</p>
30 *
31 * <p>This class is commonly used to pass configuration parameters to data store
32 * implementations during crawling operations, allowing for flexible parameter
33 * handling without tight coupling to specific parameter schemas.</p>
34 */
35 public class DataStoreParams {
36
37 /**
38 * Internal map storing parameter key-value pairs.
39 * Uses ParamMap for automatic case format conversion between camelCase and snake_case.
40 */
41 protected final Map<String, Object> params;
42
43 /**
44 * Creates a new empty DataStoreParams instance.
45 * Initializes the internal parameter map with a ParamMap wrapper.
46 */
47 public DataStoreParams() {
48 params = new ParamMap<>(new HashMap<>());
49 }
50
51 /**
52 * Creates a new DataStoreParams instance with a copy of the provided parameters.
53 * This protected constructor is used for creating new instances from existing parameter maps.
54 *
55 * @param params the parameter map to copy, must not be null
56 */
57 protected DataStoreParams(final Map<String, Object> params) {
58 this.params = new ParamMap<>(new HashMap<>(getDataMap(params)));
59 }
60
61 /**
62 * Stores a parameter value with the specified key.
63 *
64 * @param key the parameter key, must not be null
65 * @param value the parameter value, may be null
66 */
67 public void put(final String key, final Object value) {
68 params.put(key, value);
69 }
70
71 /**
72 * Retrieves a parameter value by key.
73 *
74 * @param key the parameter key to look up
75 * @return the parameter value if found, null otherwise
76 */
77 public Object get(final String key) {
78 return params.get(key);
79 }
80
81 /**
82 * Retrieves a parameter value as a String.
83 * If the stored value is already a String, it is returned directly.
84 * Otherwise, the toString() method is called on the value.
85 *
86 * @param key the parameter key to look up
87 * @return the parameter value as a String, null if not found or value is null
88 */
89 public String getAsString(final String key) {
90 if (params.get(key) instanceof final String strValue) {
91 return strValue;
92 }
93 final Object value = params.get(key);
94 if (value != null) {
95 return value.toString();
96 }
97 return null;
98 }
99
100 /**
101 * Retrieves a parameter value as a String with a default value fallback.
102 *
103 * @param key the parameter key to look up
104 * @param defaultValue the default value to return if key is not found or value is null
105 * @return the parameter value as a String, or defaultValue if not found
106 */
107 public String getAsString(final String key, final String defaultValue) {
108 final String value = getAsString(key);
109 if (value != null) {
110 return value;
111 }
112 return defaultValue;
113 }
114
115 /**
116 * Creates a new DataStoreParams instance with a copy of the current parameters.
117 * This provides an independent copy that can be modified without affecting the original.
118 *
119 * @return a new DataStoreParams instance containing a copy of the current parameters
120 */
121 public DataStoreParams newInstance() {
122 return new DataStoreParams(params);
123 }
124
125 /**
126 * Adds all key-value pairs from the specified map to this parameter container.
127 *
128 * @param map the map containing parameters to add, must not be null
129 */
130 public void putAll(final Map<String, String> map) {
131 params.putAll(map);
132 }
133
134 /**
135 * Checks if the specified key exists in the parameter map.
136 *
137 * @param key the key to check for existence
138 * @return true if the key exists, false otherwise
139 */
140 public boolean containsKey(final String key) {
141 return params.containsKey(key);
142 }
143
144 /**
145 * Returns a copy of the internal parameter map as a standard Map.
146 * The returned map is a copy and modifications will not affect this instance.
147 *
148 * @return a new Map containing all current parameters
149 */
150 public Map<String, Object> asMap() {
151 return new ParamMap<>(new HashMap<>(getDataMap(params)));
152 }
153
154 /**
155 * Extracts the underlying data map from a parameter map.
156 * If the provided map is a ParamMap instance, returns its parent map.
157 * Otherwise, returns the map as-is.
158 *
159 * @param params the parameter map to extract data from
160 * @return the underlying data map
161 */
162 protected static Map<String, Object> getDataMap(final Map<String, Object> params) {
163 if (params instanceof final ParamMap<String, Object> paramMap) {
164 return paramMap.getParent();
165 }
166 return params;
167 }
168 }