org.apache.wicket.request.component.IRequestableComponent.java Source code

Introduction

Here is the source code for org.apache.wicket.request.component.IRequestableComponent.java

Source

/*
 * 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.wicket.request.component;

import org.apache.wicket.Component;
import org.apache.wicket.WicketRuntimeException;
import org.apache.wicket.behavior.Behavior;
import org.apache.wicket.behavior.InvalidBehaviorIdException;
import org.apache.wicket.model.IDetachable;

/**
 * Base interface for components. The purpose of this interface is to make certain parts of Wicket
 * easier to mock and unit test.
 * 
 * @author Matej Knopp
 */
public interface IRequestableComponent {
    /**
     * Gets this component's path.
     * 
     * @return Colon separated path to this component in the component hierarchy
     */
    String getPageRelativePath();

    /**
     * Gets the id of this component.
     * 
     * @return The id of this component
     */
    String getId();

    /**
     * Returns page this component belongs to.
     * 
     * @return The page holding this component
     * @throws WicketRuntimeException
     *             Thrown if component is not yet attached to a Page.
     */
    IRequestablePage getPage() throws WicketRuntimeException;

    /**
     * Gets the component at the given path.
     * 
     * @param path
     *            Path to component
     * @return The component at the path
     */
    IRequestableComponent get(String path);

    /**
     * Gets a stable id for the specified behavior. The id remains stable from the point this method
     * is first called for the behavior until the behavior has been removed from the component
     * 
     * @param behavior
     * @return a stable id for the specified behavior
     */
    int getBehaviorId(Behavior behavior);

    /**
     * Gets the behavior for the specified id
     * 
     * @param id
     * @return behavior or {@code null} if none
     * @throws InvalidBehaviorIdException
     *             when behavior with this id cannot be found
     */
    Behavior getBehaviorById(int id);

    /**
     * Detaches the component.
     * <p>
     * NOTE: this method is not inherited from {@link IDetachable} on purpose. in Wicket the
     * assumption for a long time has been that {@link Component}s do not implement
     * {@link IDetachable}; doing so may lead to some very nasty side-effects. Consider
     * {@code AbstractPropertyModel#detach()} which looks like this:
     * 
     * <pre>
     * public void detach()
     * {
     *    // Detach nested object if it's a detachable
     *    if (target instanceof IDetachable)
     *    {
     *       ((IDetachable)target).detach();
     *    }
     * }
     * </pre>
     * 
     * If the model was constructed thusly, which is quite common: {@code new PropertyModel(this,
     * "person")} and {@link Component} implemented {@link IDetachable} then calling @{code
     * model.detach()} will cause an infinite loop with the model trying to detach the component and
     * the component trying to detach the model.
     * 
     * </p>
     */
    void detach();

    /**
     * @return {@code true} if it is save to call an {@link org.apache.wicket.IRequestListener} on this component
     *      when the owner page is freshly created after expiration
     */
    boolean canCallListenerAfterExpiry();
}