org.apache.sling.api.resource.Resource Maven / Gradle / Ivy
Show all versions of org.apache.sling.api Show documentation
/*
* 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.Iterator;
import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import org.apache.sling.api.adapter.Adaptable;
import aQute.bnd.annotation.ProviderType;
/**
* Resources are pieces of content on which Sling acts
*
* The Resource is also an {@link Adaptable} to get adapters to
* other types. A JCR based resource might support adapting to the JCR Node on
* which the resource is based.
*
* A Resource object is valid for as long as the
* ResourceResolver that provided this instance is valid. The
* same applies in general to all objects returned by this instance,
* especially those returned by a call to {@link #adaptTo(Class)}.
*
* All implementations must support returning a value map from
* {@link #getValueMap()}, even if the map is empty.
*
* Implementor's Note: It is recommended to not implement this interface
* directly. Rather consider either extending from {@link AbstractResource} or
* {@link ResourceWrapper}. This will make sure your implementation will not be
* suffering from missing method problems should the Sling Resource API be
* extended in the future.
*/
@ProviderType
public interface Resource extends Adaptable {
/**
* The special resource type for resource instances representing nonexisting
* resources (value is "sling:nonexisting"). This resource type is used by
* {@link ResourceResolver} instances to mark a resource which could not
* actually be resolved.
*
* @see #getResourceType()
* @see ResourceUtil#isNonExistingResource(Resource)
* @see ResourceResolver#resolve(javax.servlet.http.HttpServletRequest,
* String)
*/
String RESOURCE_TYPE_NON_EXISTING = "sling:nonexisting";
/**
* Returns the absolute path of this resource in the resource tree.
*/
@Nonnull String getPath();
/**
* Returns the name of this resource. The name of a resource is the last
* segment of the {@link #getPath() path}.
*
* @since 2.1 (Sling API Bundle 2.2.0)
*/
@Nonnull String getName();
/**
* Returns the parent resource or null if this resource
* represents the root of the resource tree.
*
* @throws org.apache.sling.api.SlingException If an error occurs trying to
* get the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
* @since 2.1 (Sling API Bundle 2.1.0)
* @see ResourceResolver#getParent(Resource)
*/
@CheckForNull Resource getParent();
/**
* Returns an iterator of the direct children of this resource.
*
* This method is a convenience and returns exactly the same resources as
* calling getResourceResolver().listChildren(resource).
*
* @throws org.apache.sling.api.SlingException If an error occurs trying to
* get the resource iterator.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
* @since 2.1 (Sling API Bundle 2.1.0)
* @see ResourceResolver#listChildren(Resource)
*/
@Nonnull Iterator listChildren();
/**
* Returns an iterable of the direct children of this resource.
*
* This method is a convenience and returns exactly the same resources as
* calling getResourceResolver().getChildren(resource).
*
* @throws org.apache.sling.api.SlingException If an error occurs trying to
* get the resource iterator.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
* @since 2.2 (Sling API Bundle 2.2.0)
* @see ResourceResolver#getChildren(Resource)
*/
@Nonnull Iterable getChildren();
/**
* Returns the child at the given relative path of this resource or
* null if no such child exists.
*
* This method is a convenience and returns exactly the same resources as
* calling getResourceResolver().getResource(resource, relPath).
*
* @throws org.apache.sling.api.SlingException If an error occurs trying to
* get the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
* @since 2.1 (Sling API Bundle 2.1.0)
* @see ResourceResolver#getResource(Resource, String)
*/
@CheckForNull Resource getChild(@Nonnull String relPath);
/**
* The resource type is meant to point to rendering/processing scripts,
* editing dialogs, etc. It is usually a path in the repository, where
* scripts and other tools definitions are found, but the
* {@link ResourceResolver} is free to set this to any suitable value such
* as the primary node type of the JCR node from which the resource is
* created.
*
* If the resource instance represents a resource which is not actually
* existing, this method returns {@link #RESOURCE_TYPE_NON_EXISTING}.
*/
@Nonnull String getResourceType();
/**
* Returns the super type of the resource if the resource defines its
* own super type. Otherwise null is returned.
* A resource might return a resource super type to overwrite the
* resource type hierarchy.
* If a client is interested in the effective resource super type
* of a resource, it should call {@link ResourceResolver#getParentResourceType(Resource)}.
* @return The super type of the resource or {@code null}.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
*/
@CheckForNull String getResourceSuperType();
/**
* Checks if the resource has any child resources.
*
* @return true if the resource has any child resources
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
* @since 2.4.4 (Sling API Bundle 2.5.0)
*/
boolean hasChildren();
/**
* Returns true if the resource type or any of the resource's
* super type(s) equals the given resource type.
*
* @param resourceType The resource type to check this resource against.
* @return true if the resource type or any of the resource's
* super type(s) equals the given resource type. false
* is also returned if resourceType is
* null.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
boolean isResourceType(String resourceType);
/**
* Returns the metadata of this resource. The concrete data contained in the
* {@link ResourceMetadata} object returned is implementation specific
* except for the {@link ResourceMetadata#RESOLUTION_PATH} property which is
* required to be set to the part of the request URI used to resolve the
* resource.
*
* @see ResourceMetadata
*/
@Nonnull ResourceMetadata getResourceMetadata();
/**
* Returns the {@link ResourceResolver} from which this resource has been
* retrieved.
*/
@Nonnull ResourceResolver getResourceResolver();
/**
* Returns a value map for this resource.
* The value map allows to read the properties of the resource.
* @return A value map
* @since 2.5 (Sling API Bundle 2.7.0)
*/
@Nonnull ValueMap getValueMap();
}