001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.    
018 */
019package org.apache.wiki.util;
020
021import java.io.File;
022import java.io.FileNotFoundException;
023import java.io.IOException;
024import java.io.InputStream;
025import java.nio.file.Files;
026import java.nio.file.Paths;
027import java.util.AbstractMap;
028import java.util.Enumeration;
029import java.util.HashMap;
030import java.util.Map;
031import java.util.Objects;
032import java.util.Properties;
033import java.util.function.Function;
034import java.util.stream.Collectors;
035
036import org.apache.commons.lang3.StringUtils;
037import org.apache.commons.lang3.Validate;
038import org.apache.logging.log4j.LogManager;
039import org.apache.logging.log4j.Logger;
040
041import jakarta.servlet.ServletContext;
042
043
044/**
045 * Property Reader for the WikiEngine. Reads the properties for the WikiEngine
046 * and implements the feature of cascading properties and variable substitution,
047 * which come in handy in a multi wiki installation environment: It reduces the
048 * need for (shell) scripting in order to generate different jspwiki.properties
049 * to a minimum.
050 *
051 * @since 2.5.x
052 */
053public final class PropertyReader {
054
055    private static final Logger LOG = LogManager.getLogger( PropertyReader.class );
056
057    /**
058     * Path to the base property file, {@value}, usually overridden by values provided in
059     * a jspwiki-custom.properties file.
060     */
061    public static final String DEFAULT_JSPWIKI_CONFIG = "/ini/jspwiki.properties";
062
063    /**
064     * The servlet context parameter (from web.xml)  that defines where the config file is to be found. If it is not defined, checks
065     * the Java System Property, if that is not defined either, uses the default as defined by DEFAULT_PROPERTYFILE.
066     * {@value #DEFAULT_JSPWIKI_CONFIG}
067     */
068    public static final String PARAM_CUSTOMCONFIG = "jspwiki.custom.config";
069
070    /**
071     *  The prefix when you are cascading properties.
072     *
073     *  @see #loadWebAppProps(ServletContext)
074     */
075    public static final String PARAM_CUSTOMCONFIG_CASCADEPREFIX = "jspwiki.custom.cascade.";
076
077    public static final String  CUSTOM_JSPWIKI_CONFIG = "/jspwiki-custom.properties";
078
079    private static final String PARAM_VAR_DECLARATION = "var.";
080    private static final String PARAM_VAR_IDENTIFIER  = "$";
081
082    /**
083     *  Private constructor to prevent instantiation.
084     */
085    private PropertyReader()
086    {}
087
088    /**
089     *  Loads the webapp properties based on servlet context information, or
090     *  (if absent) based on the Java System Property {@value #PARAM_CUSTOMCONFIG}.
091     *  Returns a Properties object containing the settings, or null if unable
092     *  to load it. (The default file is ini/jspwiki.properties, and can be
093     *  customized by setting {@value #PARAM_CUSTOMCONFIG} in the server or webapp
094     *  configuration.)
095     *
096     *  <h3>Properties sources</h3>
097     *  The following properties sources are taken into account:
098     *  <ol>
099     *      <li>JSPWiki default properties</li>
100     *      <li>System environment</li>
101     *      <li>JSPWiki custom property files</li>
102     *      <li>JSPWiki cascading properties</li>
103     *      <li>System properties</li>
104     *  </ol>
105     *  With later sources taking precedence over the previous ones. To avoid leaking system information,
106     *  only System environment and properties beginning with {@code jspwiki} (case unsensitive) are taken into account.
107     *  Also, to ease docker integration, System env properties containing "_" are turned into ".". Thus,
108     *  {@code ENV jspwiki_fileSystemProvider_pageDir} is loaded as {@code jspwiki.fileSystemProvider.pageDir}.
109     *
110     *  <h3>Cascading Properties</h3>
111     *  <p>
112     *  You can define additional property files and merge them into the default
113     *  properties file in a similar process to how you define cascading style
114     *  sheets; hence we call this <i>cascading property files</i>. This way you
115     *  can overwrite the default values and only specify the properties you
116     *  need to change in a multiple wiki environment.
117     *  <p>
118     *  You define a cascade in the context mapping of your servlet container.
119     *  <pre>
120     *  jspwiki.custom.cascade.1
121     *  jspwiki.custom.cascade.2
122     *  jspwiki.custom.cascade.3
123     *  </pre>
124     *  and so on. You have to number your cascade in a descending way starting
125     *  with "1". This means you cannot leave out numbers in your cascade. This
126     *  method is based on an idea by Olaf Kaus, see [JSPWiki:MultipleWikis].
127     *
128     *  @param context A Servlet Context which is used to find the properties
129     *  @return A filled Properties object with all the cascaded properties in place
130     */
131    public static Properties loadWebAppProps( final ServletContext context ) {
132        final String propertyFile = getInitParameter( context, PARAM_CUSTOMCONFIG );
133        try( final InputStream propertyStream = loadCustomPropertiesFile(context, propertyFile) ) {
134            final Properties props = getDefaultProperties();
135
136            // add system env properties beginning with jspwiki...
137            final Map< String, String > env = collectPropertiesFrom( System.getenv() );
138            props.putAll( env );
139
140            if( propertyStream == null ) {
141                LOG.debug( "No custom property file found, relying on JSPWiki defaults." );
142            } else {
143                props.load( propertyStream );
144            }
145
146            // this will add additional properties to the default ones:
147            LOG.debug( "Loading cascading properties..." );
148
149            // now load the cascade (new in 2.5)
150            loadWebAppPropsCascade( context, props );
151
152            // property expansion so we can resolve things like ${TOMCAT_HOME}
153            propertyExpansion( props );
154
155            // sets the JSPWiki working directory (jspwiki.workDir)
156            setWorkDir( context, props );
157
158            // add system properties beginning with jspwiki...
159            final Map< String, String > sysprops = collectPropertiesFrom( System.getProperties().stringPropertyNames().stream()
160                                                                                .collect( Collectors.toMap( Function.identity(), System::getProperty ) ) );
161            props.putAll( sysprops );
162
163            // finally, expand the variables (new in 2.5)
164            expandVars( props );
165
166            return props;
167        } catch( final Exception e ) {
168            LOG.error( "JSPWiki: Unable to load and setup properties from jspwiki.properties. " + e.getMessage(), e );
169        }
170
171        return null;
172    }
173
174    static Map< String, String > collectPropertiesFrom( final Map< String, String > map ) {
175        return map.entrySet().stream()
176                  .filter( entry -> entry.getKey().toLowerCase().startsWith( "jspwiki" ) )
177                  .map( entry -> new AbstractMap.SimpleEntry<>( entry.getKey().replace( "_", "." ), entry.getValue() ) )
178                  .collect( Collectors.toMap( Map.Entry::getKey, Map.Entry::getValue ) );
179    }
180
181    /**
182     * Figure out where our properties lie.
183     *
184     * @param context servlet context
185     * @param propertyFile property file
186     * @return InputStream holding the properties file
187     * @throws FileNotFoundException properties file not found
188     */
189    static InputStream loadCustomPropertiesFile( final ServletContext context, final String propertyFile ) throws IOException {
190        final InputStream propertyStream;
191        if( propertyFile == null ) {
192            LOG.debug( "No " + PARAM_CUSTOMCONFIG + " defined for this context, looking for custom properties file with default name of: " + CUSTOM_JSPWIKI_CONFIG );
193            //  Use the custom property file at the default location
194            propertyStream =  locateClassPathResource(context, CUSTOM_JSPWIKI_CONFIG);
195        } else {
196            LOG.debug( PARAM_CUSTOMCONFIG + " defined, using " + propertyFile + " as the custom properties file." );
197            propertyStream = Files.newInputStream( new File(propertyFile).toPath() );
198        }
199        return propertyStream;
200    }
201
202
203    /**
204     *  Returns the property set as a Properties object.
205     *
206     *  @return A property set.
207     */
208    public static Properties getDefaultProperties() {
209        final Properties props = new Properties();
210        try( final InputStream in = PropertyReader.class.getResourceAsStream( DEFAULT_JSPWIKI_CONFIG ) ) {
211            if( in != null ) {
212                props.load( in );
213            }
214        } catch( final IOException e ) {
215            LOG.error( "Unable to load default propertyfile '{}' {}", DEFAULT_JSPWIKI_CONFIG, e.getMessage(), e );
216        }
217
218        return props;
219    }
220
221    /**
222     *  Returns a property set consisting of the default Property Set overlaid with a custom property set
223     *
224     *  @param fileName Reference to the custom override file
225     *  @return A property set consisting of the default property set and custom property set, with
226     *          the latter's properties replacing the former for any common values
227     */
228    public static Properties getCombinedProperties( final String fileName ) {
229        final Properties newPropertySet = getDefaultProperties();
230        try( final InputStream in = PropertyReader.class.getResourceAsStream( fileName ) ) {
231            if( in != null ) {
232                newPropertySet.load( in );
233            } else {
234                LOG.error( "*** Custom property file \"" + fileName + "\" not found, relying on default file alone." );
235            }
236        } catch( final IOException e ) {
237            LOG.error( "Unable to load propertyfile '" + fileName + "'" + e.getMessage(), e );
238        }
239
240        return newPropertySet;
241    }
242
243    /**
244     * Returns the ServletContext Init parameter if has been set, otherwise checks for a System property of the same name. If neither are
245     * defined, returns null. This permits both Servlet- and System-defined cascading properties.
246     */
247    private static String getInitParameter( final ServletContext context, final String name ) {
248        final String value = context.getInitParameter( name );
249        return value != null ? value : System.getProperty( name ) ;
250    }
251
252
253    /**
254     *  Implement the cascade functionality.
255     *
256     * @param context             where to read the cascade from
257     * @param defaultProperties   properties to merge the cascading properties to
258     * @since 2.5.x
259     */
260    private static void loadWebAppPropsCascade( final ServletContext context, final Properties defaultProperties ) {
261        if( getInitParameter( context, PARAM_CUSTOMCONFIG_CASCADEPREFIX + "1" ) == null ) {
262            LOG.debug( " No cascading properties defined for this context" );
263            return;
264        }
265
266        // get into cascade...
267        int depth = 0;
268        while( true ) {
269            depth++;
270            final String propertyFile = getInitParameter( context, PARAM_CUSTOMCONFIG_CASCADEPREFIX + depth );
271            if( propertyFile == null ) {
272                break;
273            }
274
275            try( final InputStream propertyStream = Files.newInputStream(Paths.get(( propertyFile ) ))) {
276                LOG.info( " Reading additional properties from {} and merge to cascade.", propertyFile );
277                final Properties additionalProps = new Properties();
278                additionalProps.load( propertyStream );
279                defaultProperties.putAll( additionalProps );
280            } catch( final Exception e ) {
281                LOG.error( "JSPWiki: Unable to load and setup properties from {}. {}", propertyFile, e.getMessage() );
282            }
283        }
284    }
285
286    /**
287     * <p>Try to resolve properties whose value is something like {@code ${SOME_VALUE}} from a system property first and,
288     * if not found, from a system environment variable. If not found on neither, the property value will remain as
289     * {@code ${SOME_VALUE}}, and no more expansions will be processed.</p>
290     *
291     * <p>Several expansions per property is OK, but no we're not supporting fancy things like recursion. Reference to
292     * other properties is achieved through {@link #expandVars(Properties)}. More than one property expansion per entry
293     * is allowed.</p>
294     *
295     * @param properties properties to expand;
296     */
297    public static void propertyExpansion( final Properties properties ) {
298        final Enumeration< ? > propertyList = properties.propertyNames();
299        while( propertyList.hasMoreElements() ) {
300            final String propertyName = ( String )propertyList.nextElement();
301            String propertyValue = properties.getProperty( propertyName );
302            while( propertyValue.contains( "${" ) && propertyValue.contains( "}" ) ) {
303                final int start = propertyValue.indexOf( "${" );
304                final int end = propertyValue.indexOf( "}", start );
305                if( start >= 0 && end >= 0 && end > start ) {
306                    final String substring = propertyValue.substring( start, end ).replace( "${", "" ).replace( "}", "" );
307                    final String expansion = Objects.toString( System.getProperty( substring ), System.getenv( substring ) );
308                    if( expansion != null ) {
309                        propertyValue =  propertyValue.replace( "${" + substring + "}", expansion );
310                        properties.setProperty( propertyName, propertyValue );
311                    } else {
312                        LOG.warn( "{} referenced on {} ({}) but not found on System props or env", substring, propertyName, propertyValue );
313                        break;
314                    }
315                } else {
316                    // no more matches or value like foo}${bar
317                    break;
318                }
319            }
320        }
321    }
322
323    /**
324     *  <p>You define a property variable by using the prefix {@code var.x} as a property. In property values you can then use the "$x" identifier
325     *  to use this variable.</p>
326     *
327     *  <p>For example, you could declare a base directory for all your files like this and use it in all your other property definitions with
328     *  a {@code $basedir}. Note that it does not matter if you define the variable before its usage.
329     *  <pre>
330     *  var.basedir = /p/mywiki; # var.basedir = ${TOMCAT_HOME} would also be fine
331     *  jspwiki.fileSystemProvider.pageDir =         $basedir/www/
332     *  jspwiki.basicAttachmentProvider.storageDir = $basedir/www/
333     *  jspwiki.workDir =                            $basedir/wrk/
334     *  </pre></p>
335     *
336     * @param properties - properties to expand;
337     */
338    public static void expandVars( final Properties properties ) {
339        //get variable name/values from properties...
340        final Map< String, String > vars = new HashMap<>();
341        Enumeration< ? > propertyList = properties.propertyNames();
342        while( propertyList.hasMoreElements() ) {
343            final String propertyName = ( String )propertyList.nextElement();
344            final String propertyValue = properties.getProperty( propertyName );
345
346            if ( propertyName.startsWith( PARAM_VAR_DECLARATION ) ) {
347                final String varName = propertyName.substring( 4 ).trim();
348                final String varValue = propertyValue.trim();
349                vars.put( varName, varValue );
350            }
351        }
352
353        //now, substitute $ values in property values with vars...
354        propertyList = properties.propertyNames();
355        while( propertyList.hasMoreElements() ) {
356            final String propertyName = ( String )propertyList.nextElement();
357            String propertyValue = properties.getProperty( propertyName );
358
359            //skip var properties itself...
360            if( propertyName.startsWith( PARAM_VAR_DECLARATION ) ) {
361                continue;
362            }
363
364            for( final Map.Entry< String, String > entry : vars.entrySet() ) {
365                final String varName = entry.getKey();
366                final String varValue = entry.getValue();
367
368                //replace old property value, using the same variabe. If we don't overwrite
369                //the same one the next loop works with the original one again and
370                //multiple var expansion won't work...
371                propertyValue = TextUtil.replaceString( propertyValue, PARAM_VAR_IDENTIFIER + varName, varValue );
372
373                //add the new PropertyValue to the properties
374                properties.put( propertyName, propertyValue );
375            }
376        }
377    }
378
379    /**
380     * Locate a resource stored in the class path. Try first with "WEB-INF/classes"
381     * from the web app and fallback to "resourceName".
382     *
383     * @param context the servlet context
384     * @param resourceName the name of the resource
385     * @return the input stream of the resource or <b>null</b> if the resource was not found
386     */
387    public static InputStream locateClassPathResource( final ServletContext context, final String resourceName ) {
388        InputStream result;
389        String currResourceLocation;
390
391        // garbage in - garbage out
392        if( StringUtils.isEmpty( resourceName ) ) {
393            return null;
394        }
395
396        // try with web app class loader searching in "WEB-INF/classes"
397        currResourceLocation = createResourceLocation( "/WEB-INF/classes", resourceName );
398        result = context.getResourceAsStream( currResourceLocation );
399        if( result != null ) {
400            LOG.debug( " Successfully located the following classpath resource : " + currResourceLocation );
401            return result;
402        }
403
404        // if not found - try with the current class loader and the given name
405        currResourceLocation = createResourceLocation( "", resourceName );
406        result = PropertyReader.class.getResourceAsStream( currResourceLocation );
407        if( result != null ) {
408            LOG.debug( " Successfully located the following classpath resource : " + currResourceLocation );
409            return result;
410        }
411
412        LOG.debug( " Unable to resolve the following classpath resource : " + resourceName );
413
414        return result;
415    }
416
417    /**
418     * Create a resource location with proper usage of "/".
419     *
420     * @param path a path
421     * @param name a resource name
422     * @return a resource location
423     */
424    static String createResourceLocation( final String path, final String name ) {
425        Validate.notEmpty( name, "name is empty" );
426        final StringBuilder result = new StringBuilder();
427
428        // strip an ending "/"
429        final String sanitizedPath = ( path != null && !path.isEmpty() && path.endsWith( "/" ) ? path.substring( 0, path.length() - 1 ) : path );
430
431        // strip leading "/"
432        final String sanitizedName = ( name.startsWith( "/" ) ? name.substring( 1 ) : name );
433
434        // append the optional path
435        if( sanitizedPath != null && !sanitizedPath.isEmpty() ) {
436            if( !sanitizedPath.startsWith( "/" ) ) {
437                result.append( "/" );
438            }
439            result.append( sanitizedPath );
440        }
441        result.append( "/" );
442
443        // append the name
444        result.append( sanitizedName );
445        return result.toString();
446    }
447
448    /**
449     * This method sets the JSPWiki working directory (jspwiki.workDir). It first checks if this property
450     * is already set. If it isn't, it attempts to use the servlet container's temporary directory
451     * (jakarta.servlet.context.tempdir). If that is also unavailable, it defaults to the system's temporary
452     * directory (java.io.tmpdir).
453     * <p>
454     * This method is package-private to allow for unit testing.
455     *
456     * @param properties     the JSPWiki properties
457     * @param servletContext the Servlet context from which to fetch the tempdir if needed
458     * @since JSPWiki 2.11.1
459     */
460    static void setWorkDir( final ServletContext servletContext, final Properties properties ) {
461        final String workDir = TextUtil.getStringProperty(properties, "jspwiki.workDir", null);
462        if (workDir == null) {
463            final File tempDir = (File) servletContext.getAttribute("jakarta.servlet.context.tempdir");
464            if (tempDir != null) {
465                properties.setProperty("jspwiki.workDir", tempDir.getAbsolutePath());
466                LOG.info("Setting jspwiki.workDir to ServletContext's temporary directory: {}", tempDir.getAbsolutePath());
467            } else {
468                final String defaultTmpDir = System.getProperty("java.io.tmpdir");
469                properties.setProperty("jspwiki.workDir", defaultTmpDir);
470                LOG.info("ServletContext's temporary directory not found. Setting jspwiki.workDir to system's temporary directory: {}", defaultTmpDir);
471            }
472        } else {
473            LOG.debug("jspwiki.workDir is already set to: {}", workDir);
474        }
475    }
476
477}