001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.netbeans.modules.turbo;
042:
043: import java.util.List;
044:
045: /**
046: * SPI, extension point allowing third parties to redefine
047: * attribute reading and writing. Must be registered
048: * in default {@link org.openide.util.Lookup}.
049: * <p>
050: * It must generally deternime that they
051: * support given entity key and attribute pair
052: * and if so then perform action.
053: * <p>
054: * Two providers can theoreticaly clash and support
055: * the same attribute for the same entity key. The
056: * key point is that attribute meaning must be precisely
057: * defined guaranteeing that two independent providers
058: * respond with exactly same value hence making irrelevant
059: * which one is actually choosen.
060: * <p>
061: * Providers should not cache results.
062: *
063: * @author Petr Kuzel
064: */
065: public interface TurboProvider {
066:
067: /**
068: * Reports if an attribute is supported by the implementation.
069: */
070: boolean recognizesAttribute(String name);
071:
072: /**
073: * Reports if the entity identified by key is supported by the implementation.
074: */
075: boolean recognizesEntity(Object key);
076:
077: /**
078: * Reads given attribute for given fileobject. No method
079: * parameter may be referenced after method execution finishes.
080: *
081: * @param key identifies source entity, never <code>null</code>
082: * @param name identifies requested attribute, never <code>null</code>
083: * @param memoryCache can store speculative results
084: * @return attribute value or <code>null</code> if it does not exist.
085: */
086: Object readEntry(Object key, String name, MemoryCache memoryCache);
087:
088: /**
089: * Writes given attribute. No method
090: * parameter may be referenced after method execution finishes.
091: *
092: * @param key identifies target entity, never <code>null</code>
093: * @param name identifies attribute, never <code>null</code>
094: * @param value actual attribute value that should be stored or <code>null</code> for removing it
095: * @return <code>false</code> on write failure if provider denies the value. On I/O error it
096: * returns <code>true</code>.
097: */
098: boolean writeEntry(Object key, String name, Object value);
099:
100: /**
101: * Provides direct access to memory layer (without
102: * delegating to providers layer, here source).
103: */
104: public static final class MemoryCache {
105:
106: private final boolean enabled;
107:
108: private final List speculative;
109:
110: private final Memory memory;
111:
112: private MemoryCache(boolean enabled) {
113: this .enabled = enabled;
114: speculative = null;
115: memory = null;
116: }
117:
118: private MemoryCache(Memory memory, List speculative) {
119: enabled = true;
120: this .memory = memory;
121: this .speculative = speculative;
122: }
123:
124: /**
125: * Creates instance intercepting speculative results.
126: * @param memory implementation
127: * @param speculative add()s speculative results into it
128: */
129: static MemoryCache createDefault(Memory memory, List speculative) {
130: return new MemoryCache(memory, speculative);
131: }
132:
133: /** T9Y entry point. */
134: static MemoryCache getTest() {
135: return new MemoryCache(false);
136: }
137:
138: /**
139: * Writes speculative entry into memory layer.
140: */
141: public void cacheEntry(Object key, String name, Object value) {
142: if (enabled == false)
143: return;
144: memory.put(key, name, value);
145: if (speculative != null)
146: speculative.add(new Object[] { key, name, value });
147: }
148:
149: /** Return speculative results <code>[]{FileObject,String,Object}</code> silently inserted into memory */
150: List getSpeculative() {
151: return speculative;
152: }
153: }
154: }
|