/**
 * Copyright (c) 2015-2017 Simon Merschjohann and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 */
package org.eclipse.smarthome.automation.module.script;

import java.util.Collection;
import java.util.Map;

/**
 * A {@link ScriptExtensionProvider} can provide variable and types on ScriptEngine instance basis.
 *
 * @author Simon Merschjohann- Initial contribution
 *
 */
public interface ScriptExtensionProvider {

    /**
     * These presets will always get injected into the ScriptEngine on instance creation.
     *
     * @return collection of presets
     */
    public Collection<String> getDefaultPresets();

    /**
     * Returns the provided Presets which are supported by this ScriptExtensionProvider.
     * Presets define imports which will be injected into the ScriptEngine if called by "importPreset".
     *
     * @return provided presets
     */
    public Collection<String> getPresets();

    /**
     * Returns the supported types which can be received by the given ScriptExtensionProvider
     *
     * @return provided types
     */
    public Collection<String> getTypes();

    /**
     * This method should return an Object of the given type. Note: get can be called multiple times in the scripts use
     * caching where appropriate.
     *
     * @param scriptEngine the script engine instance requesting the given type
     * @param type
     * @return
     */
    public Object get(String scriptIdentifier, String type);

    /**
     * This method should return variables and types of the concrete type which will be injected into the ScriptEngines
     * scope.
     *
     * @param scriptEngineId - the script engine which will receive the preset
     */
    public Map<String, Object> importPreset(String scriptIdentifier, String preset);

    /**
     * This will be called when the ScriptEngine will be unloaded (e.g. if the Script is deleted or updated).
     * Every Context information stored in the ScriptExtensionProvider should be removed.
     *
     * @param scriptEngineId
     */
    public void unload(String scriptIdentifier);

}

@@ -1502,101 +1502,384 @@
 ript
-Engine the script engine instance requesting the given type%0A     * @param type%0A     * @return
+Identifier the identifier of the script that requests the given type%0A     * @param type the type that is requested (must be part of the collection returned by the %7B@code #getTypes()%7D method%0A     * @return the requested type (non-null)%0A     * @throws IllegalArgumentException if the given type does not match to one returned by the %7B@code #getTypes()%7D%0A     *             method
 %0A   
@@ -1942,16 +1942,48 @@
 ng type)
+ throws IllegalArgumentException
 ;%0A%0A    /
@@ -2150,66 +2150,144 @@
 ript
-EngineId - the script engine which will receive the preset
+Identifier the identifier of the script that receives the preset%0A     * @return the presets, must be non-null (use an empty map instead)
 %0A   
@@ -2616,15 +2616,63 @@
 ript
-EngineI
+Identifier the identifier of the script that is unloade
 d%0A  

fix JavaDoc of the script extension provider (#3568)