org.apache.sling.api.resource.ValueMap Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of org.apache.sling.api Show documentation

The Apache Sling API defines an extension to the Servlet API 2.4 to provide access to content and unified access to request parameters hiding the differences between the different methods of transferring parameters from client to server. Note that the Apache Sling API bundle does not include the Servlet API but instead requires the API to be provided by the Servlet container in which the Apache Sling framework is running or by another bundle.

There is a newer version: 2.27.6

Show newest version

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.sling.api.resource;

import java.util.Collections;
import java.util.Map;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;

import org.apache.sling.api.wrappers.ValueMapDecorator;

import aQute.bnd.annotation.ConsumerType;

/**
 * The ValueMap is an easy way to access properties of a resource.
 * With resources you can use {@link Resource#getValueMap()} to obtain the
 * value map of a resource. The various getter methods can be used to get the
 * properties of the resource.
 * 
 * In addition a value map returned by a resource supports getting of deep
 * values, like get("content/title") which is equivalent to call
 * getChild("content") on the resource, get the value map of that resource
 * and call get("title") - but without requiring to do all the checks.
 * Only the following methods support deep reads: {@link #get(Object)},
 * {@link #get(String, Class)}, {@link #get(String, Object)} and
 * {@link #containsKey(Object)}.
 *
 * A ValueMap should be immutable.
 */
@ConsumerType
public interface ValueMap extends Map {

    /**
     * Empty immutable value map.
     */
    final ValueMap EMPTY = new ValueMapDecorator(
        Collections. emptyMap());

    /**
     * Get a named property and convert it into the given type.
     * This method does not support conversion into a primitive type or an
     * array of a primitive type. It should return null in this
     * case.
     *
     * @param name The name of the property
     * @param type The class of the type
     * @return Return named value converted to type T or null if
     *         non existing or can't be converted.
     */
    @CheckForNull  T get(@Nonnull String name, @Nonnull Class type);

    /**
     * Get a named property and convert it into the given type.
     * This method does not support conversion into a primitive type or an
     * array of a primitive type. It should return the default value in this
     * case.
     *
     * @param name The name of the property
     * @param defaultValue The default value to use if the named property does
     *            not exist or cannot be converted to the requested type. The
     *            default value is also used to define the type to convert the
     *            value to. If this is null any existing property is
     *            not converted.
     * @return Return named value converted to type T or the default value if
     *         non existing or can't be converted.
     */
     T get(@Nonnull String name, T defaultValue);
}