001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.scripting;
018
019import java.io.IOException;
020
021import org.springframework.lang.Nullable;
022
023/**
024 * Script definition interface, encapsulating the configuration
025 * of a specific script as well as a factory method for
026 * creating the actual scripted Java {@code Object}.
027 *
028 * @author Juergen Hoeller
029 * @author Rob Harrop
030 * @since 2.0
031 * @see #getScriptSourceLocator
032 * @see #getScriptedObject
033 */
034public interface ScriptFactory {
035
036        /**
037         * Return a locator that points to the source of the script.
038         * Interpreted by the post-processor that actually creates the script.
039         * <p>Typical supported locators are Spring resource locations
040         * (such as "file:C:/myScript.bsh" or "classpath:myPackage/myScript.bsh")
041         * and inline scripts ("inline:myScriptText...").
042         * @return the script source locator
043         * @see org.springframework.scripting.support.ScriptFactoryPostProcessor#convertToScriptSource
044         * @see org.springframework.core.io.ResourceLoader
045         */
046        String getScriptSourceLocator();
047
048        /**
049         * Return the business interfaces that the script is supposed to implement.
050         * <p>Can return {@code null} if the script itself determines
051         * its Java interfaces (such as in the case of Groovy).
052         * @return the interfaces for the script
053         */
054        @Nullable
055        Class<?>[] getScriptInterfaces();
056
057        /**
058         * Return whether the script requires a config interface to be
059         * generated for it. This is typically the case for scripts that
060         * do not determine Java signatures themselves, with no appropriate
061         * config interface specified in {@code getScriptInterfaces()}.
062         * @return whether the script requires a generated config interface
063         * @see #getScriptInterfaces()
064         */
065        boolean requiresConfigInterface();
066
067        /**
068         * Factory method for creating the scripted Java object.
069         * <p>Implementations are encouraged to cache script metadata such as
070         * a generated script class. Note that this method may be invoked
071         * concurrently and must be implemented in a thread-safe fashion.
072         * @param scriptSource the actual ScriptSource to retrieve
073         * the script source text from (never {@code null})
074         * @param actualInterfaces the actual interfaces to expose,
075         * including script interfaces as well as a generated config interface
076         * (if applicable; may be {@code null})
077         * @return the scripted Java object
078         * @throws IOException if script retrieval failed
079         * @throws ScriptCompilationException if script compilation failed
080         */
081        @Nullable
082        Object getScriptedObject(ScriptSource scriptSource, @Nullable Class<?>... actualInterfaces)
083                        throws IOException, ScriptCompilationException;
084
085        /**
086         * Determine the type of the scripted Java object.
087         * <p>Implementations are encouraged to cache script metadata such as
088         * a generated script class. Note that this method may be invoked
089         * concurrently and must be implemented in a thread-safe fashion.
090         * @param scriptSource the actual ScriptSource to retrieve
091         * the script source text from (never {@code null})
092         * @return the type of the scripted Java object, or {@code null}
093         * if none could be determined
094         * @throws IOException if script retrieval failed
095         * @throws ScriptCompilationException if script compilation failed
096         * @since 2.0.3
097         */
098        @Nullable
099        Class<?> getScriptedObjectType(ScriptSource scriptSource)
100                        throws IOException, ScriptCompilationException;
101
102        /**
103         * Determine whether a refresh is required (e.g. through
104         * ScriptSource's {@code isModified()} method).
105         * @param scriptSource the actual ScriptSource to retrieve
106         * the script source text from (never {@code null})
107         * @return whether a fresh {@link #getScriptedObject} call is required
108         * @since 2.5.2
109         * @see ScriptSource#isModified()
110         */
111        boolean requiresScriptedObjectRefresh(ScriptSource scriptSource);
112
113}