001package org.apache.commons.beanutils2;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022/**
023 * Provides access to constructors and static methods on a class.
024 *
025 * @param <B> The type modeled by this {@code ClassAccessor}.
026 */
027public interface ClassAccessor<B>
028{
029
030    // constructors
031
032    /**
033     * Creates a new instance of type {@code B} by calling the parameterless constructor of the wrapped class.
034     *
035     * @return a {@link BeanAccessor} that wraps the new instance.
036     * @throws BeanInstantiationException if the class wrapped by this {@code ClassAccessor} is not instantiable (for
037     *             example if it is a primitive type).
038     * @throws NoSuchConstructorException if the class wrapped by this {@code ClassAccessor} does not provide a default
039     *             constructor.
040     * @throws ConstructorNotAccessibleException if the constructor is not accessible.
041     * @throws ConstructorInvocationException if the constructor invocation threw an exception.
042     */
043    BeanAccessor<B> newInstance();
044
045    /**
046     * Invokes the constructor with the parameter list represented by {@code arguments} on the wrapped class. Primitive
047     * types may be converted to wrapper types and vice versa to match the methods signature.
048     *
049     * @param arguments the list of arguments to invoke the constructor with. None of the {@code Argument} objects must
050     *            be {@code null}. If you want to pass {@code null} to the constructor use
051     *            {@link Argument#nullArgument(Class)}.
052     * @return a {@link BeanAccessor} that wrapped the new instance
053     * @throws BeanInstantiationException if the class wrapped by this {@code ClassAccessor} is not instantiable (for
054     *             example if it is a primitive type).
055     * @throws NoSuchConstructorException if no constructor that matches {@code arguments} can be found.
056     * @throws ConstructorNotAccessibleException if the constructor is not accessible.
057     * @throws ConstructorInvocationException if the constructor invocation threw an exception.
058     */
059    BeanAccessor<B> invokeConstructor( Argument<?>... arguments );
060
061    /**
062     * Invokes the constructor with the parameter list represented by {@code arguments} on the wrapped class. Invoking
063     * an exact constructor in this context means to not perform any type conversations during invocation.
064     *
065     * @param arguments the list of arguments to invoke the constructor with. None of the {@code Argument} objects must
066     *            be {@code null}. If you want to pass {@code null} to the constructor use
067     *            {@link Argument#nullArgument(Class)}.
068     * @return a {@link BeanAccessor} that wrapped the new instance
069     * @throws BeanInstantiationException if the class wrapped by this {@code ClassAccessor} is not instantiable (for
070     *             example if it is a primitive type).
071     * @throws NoSuchConstructorException if no constructor that matches {@code arguments} exactly (without type
072     *             conversation) can be found.
073     * @throws ConstructorNotAccessibleException if the constructor is not accessible.
074     * @throws ConstructorInvocationException if the constructor invocation threw an exception.
075     */
076    BeanAccessor<B> invokeExactConstructor( Argument<?>... arguments );
077
078    // bean properties
079
080    /**
081     * Provides access to the {@link BeanProperties} defined by the wrapped class.
082     *
083     * @return the {@link BeanProperties} for the wrapped class.
084     */
085    BeanProperties<B> getProperties();
086
087    // static methods invocation
088
089    /**
090     * Invokes the method with name {@code methodName} on the wrapped class. Primitive types may be converted to wrapper
091     * types and vice versa to match the methods signature.
092     *
093     * @param methodName the name of the method to invoke. Must not be {@code null}!
094     * @return the {@link ArgumentsAccessor} for this method invocation.
095     */
096    ArgumentsAccessor invokeStatic( String methodName );
097
098    /**
099     * Invokes the method with name {@code methodName} on the wrapped class. Invoking an exact method in this context
100     * means to not perform any type conversations during invocation.
101     *
102     * @param methodName the name of the method to invoke. Must not be {@code null}!
103     * @return the {@link ArgumentsAccessor} for this method invocation.
104     */
105    ArgumentsAccessor invokeExactStatic( String methodName );
106
107}