attila@90: /*
attila@90:  * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
attila@90:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
attila@90:  *
attila@90:  * This code is free software; you can redistribute it and/or modify it
attila@90:  * under the terms of the GNU General Public License version 2 only, as
attila@90:  * published by the Free Software Foundation.  Oracle designates this
attila@90:  * particular file as subject to the "Classpath" exception as provided
attila@90:  * by Oracle in the LICENSE file that accompanied this code.
attila@90:  *
attila@90:  * This code is distributed in the hope that it will be useful, but WITHOUT
attila@90:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
attila@90:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
attila@90:  * version 2 for more details (a copy is included in the LICENSE file that
attila@90:  * accompanied this code).
attila@90:  *
attila@90:  * You should have received a copy of the GNU General Public License version
attila@90:  * 2 along with this work; if not, write to the Free Software Foundation,
attila@90:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
attila@90:  *
attila@90:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
attila@90:  * or visit www.oracle.com if you need additional information or have any
attila@90:  * questions.
attila@90:  */
attila@90: 
attila@90: /*
attila@90:  * This file is available under and governed by the GNU General Public
attila@90:  * License version 2 only, as published by the Free Software Foundation.
attila@90:  * However, the following notice accompanied the original version of this
attila@90:  * file, and Oracle licenses the original version of this file under the BSD
attila@90:  * license:
attila@90:  */
attila@90: /*
attila@90:    Copyright 2009-2013 Attila Szegedi
attila@90: 
attila@90:    Licensed under both the Apache License, Version 2.0 (the "Apache License")
attila@90:    and the BSD License (the "BSD License"), with licensee being free to
attila@90:    choose either of the two at their discretion.
attila@90: 
attila@90:    You may not use this file except in compliance with either the Apache
attila@90:    License or the BSD License.
attila@90: 
attila@90:    If you choose to use this file in compliance with the Apache License, the
attila@90:    following notice applies to you:
attila@90: 
attila@90:        You may obtain a copy of the Apache License at
attila@90: 
attila@90:            http://www.apache.org/licenses/LICENSE-2.0
attila@90: 
attila@90:        Unless required by applicable law or agreed to in writing, software
attila@90:        distributed under the License is distributed on an "AS IS" BASIS,
attila@90:        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
attila@90:        implied. See the License for the specific language governing
attila@90:        permissions and limitations under the License.
attila@90: 
attila@90:    If you choose to use this file in compliance with the BSD License, the
attila@90:    following notice applies to you:
attila@90: 
attila@90:        Redistribution and use in source and binary forms, with or without
attila@90:        modification, are permitted provided that the following conditions are
attila@90:        met:
attila@90:        * Redistributions of source code must retain the above copyright
attila@90:          notice, this list of conditions and the following disclaimer.
attila@90:        * Redistributions in binary form must reproduce the above copyright
attila@90:          notice, this list of conditions and the following disclaimer in the
attila@90:          documentation and/or other materials provided with the distribution.
attila@90:        * Neither the name of the copyright holder nor the names of
attila@90:          contributors may be used to endorse or promote products derived from
attila@90:          this software without specific prior written permission.
attila@90: 
attila@90:        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
attila@90:        IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
attila@90:        TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
attila@90:        PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
attila@90:        BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
attila@90:        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
attila@90:        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
attila@90:        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
attila@90:        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
attila@90:        OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
attila@90:        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
attila@90: */
attila@90: 
attila@90: package jdk.internal.dynalink;
attila@90: 
attila@90: import java.lang.invoke.MutableCallSite;
attila@488: import java.security.AccessController;
attila@488: import java.security.PrivilegedAction;
attila@90: import java.util.ArrayList;
attila@90: import java.util.Arrays;
attila@90: import java.util.Collections;
attila@90: import java.util.HashSet;
attila@90: import java.util.LinkedList;
attila@90: import java.util.List;
attila@90: import java.util.Set;
attila@90: import jdk.internal.dynalink.beans.BeansLinker;
attila@90: import jdk.internal.dynalink.linker.GuardingDynamicLinker;
attila@90: import jdk.internal.dynalink.linker.GuardingTypeConverterFactory;
attila@90: import jdk.internal.dynalink.linker.LinkRequest;
attila@1090: import jdk.internal.dynalink.linker.MethodTypeConversionStrategy;
attila@90: import jdk.internal.dynalink.support.AutoDiscovery;
attila@90: import jdk.internal.dynalink.support.BottomGuardingDynamicLinker;
attila@494: import jdk.internal.dynalink.support.ClassLoaderGetterContextProvider;
attila@90: import jdk.internal.dynalink.support.CompositeGuardingDynamicLinker;
attila@90: import jdk.internal.dynalink.support.CompositeTypeBasedGuardingDynamicLinker;
attila@963: import jdk.internal.dynalink.support.DefaultPrelinkFilter;
attila@90: import jdk.internal.dynalink.support.LinkerServicesImpl;
attila@90: import jdk.internal.dynalink.support.TypeConverterFactory;
attila@1090: import jdk.internal.dynalink.support.TypeUtilities;
attila@90: 
attila@90: /**
attila@90:  * A factory class for creating {@link DynamicLinker}s. The most usual dynamic linker is a linker that is a composition
attila@90:  * of all {@link GuardingDynamicLinker}s known and pre-created by the caller as well as any
attila@963:  * {@link AutoDiscovery automatically discovered} guarding linkers and the standard fallback {@link BeansLinker} and a
attila@963:  * {@link DefaultPrelinkFilter}. See {@link DynamicLinker} documentation for tips on how to use this class.
attila@90:  *
attila@90:  * @author Attila Szegedi
attila@90:  */
attila@90: public class DynamicLinkerFactory {
attila@90:     /**
attila@90:      * Default value for {@link #setUnstableRelinkThreshold(int) unstable relink threshold}.
attila@90:      */
attila@90:     public static final int DEFAULT_UNSTABLE_RELINK_THRESHOLD = 8;
attila@90: 
attila@488:     private boolean classLoaderExplicitlySet = false;
attila@488:     private ClassLoader classLoader;
attila@488: 
attila@90:     private List<? extends GuardingDynamicLinker> prioritizedLinkers;
attila@90:     private List<? extends GuardingDynamicLinker> fallbackLinkers;
attila@90:     private int runtimeContextArgCount = 0;
attila@90:     private boolean syncOnRelink = false;
attila@90:     private int unstableRelinkThreshold = DEFAULT_UNSTABLE_RELINK_THRESHOLD;
attila@963:     private GuardedInvocationFilter prelinkFilter;
attila@1090:     private MethodTypeConversionStrategy autoConversionStrategy;
attila@90: 
attila@90:     /**
attila@90:      * Sets the class loader for automatic discovery of available linkers. If not set explicitly, then the thread
attila@488:      * context class loader at the time of {@link #createLinker()} invocation will be used.
attila@90:      *
attila@90:      * @param classLoader the class loader used for the autodiscovery of available linkers.
attila@90:      */
attila@962:     public void setClassLoader(final ClassLoader classLoader) {
attila@90:         this.classLoader = classLoader;
attila@488:         classLoaderExplicitlySet = true;
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the prioritized linkers. Language runtimes using this framework will usually precreate at least the linker
attila@90:      * for their own language. These linkers will be consulted first in the resulting dynamic linker, before any
attila@90:      * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the prioritized
attila@90:      * linkers, it will be ignored and the explicit prioritized instance will be used.
attila@90:      *
attila@90:      * @param prioritizedLinkers the list of prioritized linkers. Null can be passed to indicate no prioritized linkers
attila@90:      * (this is also the default value).
attila@90:      */
attila@962:     public void setPrioritizedLinkers(final List<? extends GuardingDynamicLinker> prioritizedLinkers) {
attila@90:         this.prioritizedLinkers =
attila@90:                 prioritizedLinkers == null ? null : new ArrayList<>(prioritizedLinkers);
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the prioritized linkers. Language runtimes using this framework will usually precreate at least the linker
attila@90:      * for their own language. These linkers will be consulted first in the resulting dynamic linker, before any
attila@90:      * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the prioritized
attila@90:      * linkers, it will be ignored and the explicit prioritized instance will be used.
attila@90:      *
attila@90:      * @param prioritizedLinkers a list of prioritized linkers.
attila@90:      */
attila@962:     public void setPrioritizedLinkers(final GuardingDynamicLinker... prioritizedLinkers) {
attila@90:         setPrioritizedLinkers(Arrays.asList(prioritizedLinkers));
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets a single prioritized linker. Identical to calling {@link #setPrioritizedLinkers(List)} with a single-element
attila@90:      * list.
attila@90:      *
attila@90:      * @param prioritizedLinker the single prioritized linker. Must not be null.
attila@90:      * @throws IllegalArgumentException if null is passed.
attila@90:      */
attila@962:     public void setPrioritizedLinker(final GuardingDynamicLinker prioritizedLinker) {
attila@90:         if(prioritizedLinker == null) {
attila@90:             throw new IllegalArgumentException("prioritizedLinker == null");
attila@90:         }
attila@90:         this.prioritizedLinkers = Collections.singletonList(prioritizedLinker);
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the fallback linkers. These linkers will be consulted last in the resulting composite linker, after any
attila@90:      * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the fallback
attila@90:      * linkers, it will be ignored and the explicit fallback instance will be used.
attila@90:      *
attila@90:      * @param fallbackLinkers the list of fallback linkers. Can be empty to indicate the caller wishes to set no
attila@90:      * fallback linkers.
attila@90:      */
attila@962:     public void setFallbackLinkers(final List<? extends GuardingDynamicLinker> fallbackLinkers) {
attila@90:         this.fallbackLinkers = fallbackLinkers == null ? null : new ArrayList<>(fallbackLinkers);
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the fallback linkers. These linkers will be consulted last in the resulting composite linker, after any
attila@90:      * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the fallback
attila@90:      * linkers, it will be ignored and the explicit fallback instance will be used.
attila@90:      *
attila@90:      * @param fallbackLinkers the list of fallback linkers. Can be empty to indicate the caller wishes to set no
attila@90:      * fallback linkers. If it is left as null, the standard fallback {@link BeansLinker} will be used.
attila@90:      */
attila@962:     public void setFallbackLinkers(final GuardingDynamicLinker... fallbackLinkers) {
attila@90:         setFallbackLinkers(Arrays.asList(fallbackLinkers));
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the number of arguments in the call sites that represent the stack context of the language runtime creating
attila@90:      * the linker. If the language runtime uses no context information passed on stack, then it should be zero
attila@90:      * (the default value). If it is set to nonzero value, then every dynamic call site emitted by this runtime must
attila@90:      * have the argument list of the form: {@code (this, contextArg1[, contextArg2[, ...]], normalArgs)}. It is
attila@90:      * advisable to only pass one context-specific argument, though, of an easily recognizable, runtime specific type
attila@90:      * encapsulating the runtime thread local state.
attila@90:      *
attila@90:      * @param runtimeContextArgCount the number of language runtime context arguments in call sites.
attila@90:      */
attila@962:     public void setRuntimeContextArgCount(final int runtimeContextArgCount) {
attila@90:         if(runtimeContextArgCount < 0) {
attila@90:             throw new IllegalArgumentException("runtimeContextArgCount < 0");
attila@90:         }
attila@90:         this.runtimeContextArgCount = runtimeContextArgCount;
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets whether the linker created by this factory will invoke {@link MutableCallSite#syncAll(MutableCallSite[])}
attila@90:      * after a call site is relinked. Defaults to false. You probably want to set it to true if your runtime supports
attila@90:      * multithreaded execution of dynamically linked code.
attila@90:      * @param syncOnRelink true for invoking sync on relink, false otherwise.
attila@90:      */
attila@962:     public void setSyncOnRelink(final boolean syncOnRelink) {
attila@90:         this.syncOnRelink = syncOnRelink;
attila@90:     }
attila@90: 
attila@90:     /**
attila@90:      * Sets the unstable relink threshold; the number of times a call site is relinked after which it will be
attila@90:      * considered unstable, and subsequent link requests for it will indicate this.
attila@90:      * @param unstableRelinkThreshold the new threshold. Must not be less than zero. The value of zero means that
attila@90:      * call sites will never be considered unstable.
attila@90:      * @see LinkRequest#isCallSiteUnstable()
attila@90:      */
attila@962:     public void setUnstableRelinkThreshold(final int unstableRelinkThreshold) {
attila@90:         if(unstableRelinkThreshold < 0) {
attila@90:             throw new IllegalArgumentException("unstableRelinkThreshold < 0");
attila@90:         }
attila@90:         this.unstableRelinkThreshold = unstableRelinkThreshold;
attila@90:     }
attila@90: 
attila@90:     /**
attila@963:      * Set the pre-link filter. This is a {@link GuardedInvocationFilter} that will get the final chance to modify the
attila@963:      * guarded invocation after it has been created by a component linker and before the dynamic linker links it into
attila@963:      * the call site. It is normally used to adapt the return value type of the invocation to the type of the call site.
attila@963:      * When not set explicitly, {@link DefaultPrelinkFilter} will be used.
attila@963:      * @param prelinkFilter the pre-link filter for the dynamic linker.
attila@963:      */
attila@963:     public void setPrelinkFilter(final GuardedInvocationFilter prelinkFilter) {
attila@963:         this.prelinkFilter = prelinkFilter;
attila@963:     }
attila@963: 
attila@963:     /**
attila@1090:      * Sets an object representing the conversion strategy for automatic type conversions. After
attila@1090:      * {@link TypeConverterFactory#asType(java.lang.invoke.MethodHandle, java.lang.invoke.MethodType)} has
attila@1090:      * applied all custom conversions to a method handle, it still needs to effect
attila@1090:      * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class) method invocation conversions} that
attila@1090:      * can usually be automatically applied as per
attila@1090:      * {@link java.lang.invoke.MethodHandle#asType(java.lang.invoke.MethodType)}.
attila@1090:      * However, sometimes language runtimes will want to customize even those conversions for their own call
attila@1090:      * sites. A typical example is allowing unboxing of null return values, which is by default prohibited by
attila@1090:      * ordinary {@code MethodHandles.asType}. In this case, a language runtime can install its own custom
attila@1090:      * automatic conversion strategy, that can deal with null values. Note that when the strategy's
attila@1090:      * {@link MethodTypeConversionStrategy#asType(java.lang.invoke.MethodHandle, java.lang.invoke.MethodType)}
attila@1090:      * is invoked, the custom language conversions will already have been applied to the method handle, so by
attila@1090:      * design the difference between the handle's current method type and the desired final type will always
attila@1090:      * only be ones that can be subjected to method invocation conversions. The strategy also doesn't need to
attila@1090:      * invoke a final {@code MethodHandle.asType()} as the converter factory will do that as the final step.
attila@1090:      * @param autoConversionStrategy the strategy for applying method invocation conversions for the linker
attila@1090:      * created by this factory.
attila@1090:      */
attila@1090:     public void setAutoConversionStrategy(final MethodTypeConversionStrategy autoConversionStrategy) {
attila@1090:         this.autoConversionStrategy = autoConversionStrategy;
attila@1090:     }
attila@1090: 
attila@1090:     /**
attila@963:      * Creates a new dynamic linker consisting of all the prioritized, autodiscovered, and fallback linkers as well as
attila@963:      * the pre-link filter.
attila@90:      *
attila@90:      * @return the new dynamic Linker
attila@90:      */
attila@90:     public DynamicLinker createLinker() {
attila@90:         // Treat nulls appropriately
attila@90:         if(prioritizedLinkers == null) {
attila@90:             prioritizedLinkers = Collections.emptyList();
attila@90:         }
attila@90:         if(fallbackLinkers == null) {
attila@90:             fallbackLinkers = Collections.singletonList(new BeansLinker());
attila@90:         }
attila@90: 
attila@90:         // Gather classes of all precreated (prioritized and fallback) linkers.
attila@90:         // We'll filter out any discovered linkers of the same class.
attila@101:         final Set<Class<? extends GuardingDynamicLinker>> knownLinkerClasses =
attila@101:                 new HashSet<>();
attila@90:         addClasses(knownLinkerClasses, prioritizedLinkers);
attila@90:         addClasses(knownLinkerClasses, fallbackLinkers);
attila@90: 
attila@488:         final ClassLoader effectiveClassLoader = classLoaderExplicitlySet ? classLoader : getThreadContextClassLoader();
attila@488:         final List<GuardingDynamicLinker> discovered = AutoDiscovery.loadLinkers(effectiveClassLoader);
attila@90:         // Now, concatenate ...
attila@101:         final List<GuardingDynamicLinker> linkers =
attila@101:                 new ArrayList<>(prioritizedLinkers.size() + discovered.size()
attila@101:                         + fallbackLinkers.size());
attila@90:         // ... prioritized linkers, ...
attila@90:         linkers.addAll(prioritizedLinkers);
attila@90:         // ... filtered discovered linkers, ...
attila@962:         for(final GuardingDynamicLinker linker: discovered) {
attila@90:             if(!knownLinkerClasses.contains(linker.getClass())) {
attila@90:                 linkers.add(linker);
attila@90:             }
attila@90:         }
attila@90:         // ... and finally fallback linkers.
attila@90:         linkers.addAll(fallbackLinkers);
attila@90:         final List<GuardingDynamicLinker> optimized = CompositeTypeBasedGuardingDynamicLinker.optimize(linkers);
attila@90:         final GuardingDynamicLinker composite;
attila@90:         switch(linkers.size()) {
attila@90:             case 0: {
attila@90:                 composite = BottomGuardingDynamicLinker.INSTANCE;
attila@90:                 break;
attila@90:             }
attila@90:             case 1: {
attila@90:                 composite = optimized.get(0);
attila@90:                 break;
attila@90:             }
attila@90:             default: {
attila@90:                 composite = new CompositeGuardingDynamicLinker(optimized);
attila@90:                 break;
attila@90:             }
attila@90:         }
attila@90: 
attila@90:         final List<GuardingTypeConverterFactory> typeConverters = new LinkedList<>();
attila@962:         for(final GuardingDynamicLinker linker: linkers) {
attila@90:             if(linker instanceof GuardingTypeConverterFactory) {
attila@90:                 typeConverters.add((GuardingTypeConverterFactory)linker);
attila@90:             }
attila@90:         }
attila@90: 
attila@963:         if(prelinkFilter == null) {
attila@963:             prelinkFilter = new DefaultPrelinkFilter();
attila@963:         }
attila@963: 
attila@1090:         return new DynamicLinker(new LinkerServicesImpl(new TypeConverterFactory(typeConverters,
attila@1090:                 autoConversionStrategy), composite), prelinkFilter, runtimeContextArgCount, syncOnRelink,
attila@1090:                 unstableRelinkThreshold);
attila@90:     }
attila@90: 
attila@488:     private static ClassLoader getThreadContextClassLoader() {
attila@488:         return AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
attila@488:             @Override
attila@488:             public ClassLoader run() {
attila@488:                 return Thread.currentThread().getContextClassLoader();
attila@488:             }
attila@494:         }, ClassLoaderGetterContextProvider.GET_CLASS_LOADER_CONTEXT);
attila@488:     }
attila@488: 
attila@962:     private static void addClasses(final Set<Class<? extends GuardingDynamicLinker>> knownLinkerClasses,
attila@962:             final List<? extends GuardingDynamicLinker> linkers) {
attila@962:         for(final GuardingDynamicLinker linker: linkers) {
attila@90:             knownLinkerClasses.add(linker.getClass());
attila@90:         }
attila@90:     }
attila@101: }