1 /******************************************************************************* 2 * Copyright (c) 2009, 2012 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.e4.core.di.suppliers; 15 16 import java.lang.ref.WeakReference; 17 18 /** 19 * The base class for an "object supplier" - something that knows how to 20 * instantiate objects corresponding to the object descriptor. 21 * <p> 22 * If supplier is asked to track changes, it should notify requestor whenever 23 * any of the objects produced by the 24 * {@link #get(IObjectDescriptor[], Object[], IRequestor, boolean, boolean, boolean)} 25 * method change. The supplier can do this by performing calls to the 26 * {@link IRequestor#resolveArguments(boolean)} and 27 * {@link IRequestor#execute()}. 28 * </p> 29 * 30 * @see IRequestor#resolveArguments(boolean) 31 * @see IRequestor#execute() 32 * @since 1.7 33 */ 34 abstract public class PrimaryObjectSupplier { 35 36 /** 37 * Default constructor 38 */ PrimaryObjectSupplier()39 public PrimaryObjectSupplier() { 40 // placeholder 41 } 42 43 /** 44 * This method is called by the dependency injection mechanism to obtain objects corresponding 45 * to the object descriptors. If the supplier is asked to track changes, it should notify requestor 46 * whenever it detects a change that would result in a different result produced by this method. 47 * @param descriptors descriptors to the objects requested by the requestor 48 * @param actualValues the values of actual arguments computed so far for the descriptors (in/out) 49 * @param requestor the requestor originating this request 50 * @param initial <code>true</code> true if this is the initial request from the requestor 51 * @param track <code>true</code> if the object suppliers should notify requestor of 52 * changes to the returned objects; <code>false</code> otherwise 53 * @param group <code>true</code> if the change notifications can be grouped; 54 * <code>false</code> otherwise 55 */ get(IObjectDescriptor[] descriptors, Object[] actualValues, IRequestor requestor, boolean initial, boolean track, boolean group)56 abstract public void get(IObjectDescriptor[] descriptors, Object[] actualValues, IRequestor requestor, boolean initial, boolean track, boolean group); 57 58 /** 59 * Pause tracking access to the supplier's objects. 60 */ pauseRecording()61 abstract public void pauseRecording(); 62 63 /** 64 * Resume tracking access to the supplier's objects. 65 */ resumeRecording()66 abstract public void resumeRecording(); 67 68 /** 69 * Creates a new reference to the object. 70 * <p> 71 * Suppliers may override to provide improved memory management, for instance, by 72 * to tracking references with reference queues. 73 * </p> 74 * @param object the referred object 75 * @return a new weak reference to the object 76 */ makeReference(Object object)77 public WeakReference<Object> makeReference(Object object) { 78 return new WeakReference<>(object); 79 } 80 } 81