+ Intent is an description of some intended operation. It is specified
+ by action type (String) and a URI. When some Intent is executed,
+ proper handler is chosen and it performs the actual operation.
+
+
+ Intents provide loose coupling between modules that may request an
+ operation and modules that can perform it. They can be easily
+ serialized, so they are suitable for distributed heterogenous
+ systems.
+
+
+
+
+ API for describing and executing intended operations.
+
+
+
+
+ SPI for handlers that are able to invoke proper operation for
+ specified intents.
+
+
+
+
+
+
+
+
+
+ The code is checked by unit tests.
+
+
+
+
+
+
+
+
+ Done.
+
+
+
+
+
+
+
+
+
+ Future<Object> result = new Intent(Intent.ACTION_VIEW, new URI("scheme://path/")).execute();
+ Object value = result.get();
+
+
+
+
+
+ new Intent(Intent.ACTION_VIEW, new URI("scheme://path/")).execute(new Callback() {
+ void success(Object result) {
+ // use the result somehow
+ }
+ void failure(Exception exception) {
+ // report the failure somehow
+ }
+ });
+
+
+
+
+
+ @IntentHandlerRegistration(
+ displayName = "Show my item in MyEditor",
+ position = 800,
+ uriPattern = "myscheme://.*",
+ actions = {Intent.ACTION_VIEW, Intent.ACTION_EDIT}
+ )
+ public static Object handleIntent(Intent intent) {
+ SomeType result = parseAndPerformIntentSomehow(intent);
+ return result;
+ }
+
+
+
+
+
+ @IntentHandlerRegistration(
+ displayName = "Show my item in MyEditor",
+ position = 800,
+ uriPattern = "myscheme://.*",
+ actions = "*"
+ )
+ public static void handleIntent(final Intent intent, final Result result) {
+ // Move the execution to another thread. Do not wait for the result
+ // here, just pass the result object.
+ EventQueue.invokeLater(new Runnable() {
+ public void run() {
+ try {
+ Object result = doSomethingInEDT(intent);
+ result.setResult(e);
+ } catch (Exception e) {
+ result.setException(e);
+ }
+ }
+ });
+ }
+
+
+
+
+
+
+
+
+
+ This module provides a contract between API clients that can express
+ some intention to invoke an operation and SPI providers that can
+ handle that intention.
+
+
+ This is useful in client-server environments, where the intention
+ can be constructed on server-side, but handled on client-side. The
+ objects that describe the intention should be easy to construct,
+ transfer and interpret.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ No deprecation needed.
+
+
+
+
+
+
+
+
+ Yes.
+
+
+
+
+
+
+
+
+ No standards.
+
+
+
+
+
+
+
+
+ No settings are read or written.
+
+
+
+
+
+
+
+
+ 1.6
+
+
+
+
+
+
+
+
+ JRE
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ No non-NB dependencies.
+
+
+
+
+
+
+
+
+ Any platform.
+
+
+
+
+
+
+
+
+ Standard module dependency is sufficient.
+
+
+
+
+
+
+
+
+ Just module JAR.
+
+
+
+
+
+
+
+
+ Yes.
+
+
+
+
+
+
+
+
+ Only API and SPI packages are public.
+
+
+
+
+
+
+
+
+ Installation location does not matter.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ The API is threadsafe. SPI implementations should ensure proper
+ synchronization.
+
+
+
+
+
+
+
+
+ No clipboard access.
+
+
+
+
+
+
+
+
+ No Drag & Drop support.
+
+
+
+
+
+
+
+
+ No files are read or written by this module.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ The annotation processor is registered using ServiceProvider.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ Very little memory consumed.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ Code in the module is very simple. Performance is incluenced mosly
+ by SPI implementations, which should run quite quickly.
+
+
+
+
+
+
+
+
+ No performance criteria are enforced. The plugged-in code is invoked
+ by a dedicated executor.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
+
+
+
+
+ No.
+
+
+
+
--- a/api.intent/build.xml
+++ a/api.intent/build.xml
@@ -0,0 +1,5 @@
+
+
+ Builds, tests, and runs the project org.netbeans.api.intent
+
+
--- a/api.intent/manifest.mf
+++ a/api.intent/manifest.mf
@@ -0,0 +1,6 @@
+Manifest-Version: 1.0
+AutoUpdate-Show-In-Client: true
+OpenIDE-Module: org.netbeans.api.intent
+OpenIDE-Module-Localizing-Bundle: org/netbeans/api/intent/Bundle.properties
+OpenIDE-Module-Specification-Version: 1.0
+
--- a/api.intent/nbproject/project.properties
+++ a/api.intent/nbproject/project.properties
@@ -0,0 +1,4 @@
+is.autoload=true
+javac.source=1.7
+javac.compilerargs=-Xlint -Xlint:-serial
+javadoc.arch=${basedir}/arch.xml
--- a/api.intent/nbproject/project.xml
+++ a/api.intent/nbproject/project.xml
@@ -0,0 +1,61 @@
+
+
+ org.netbeans.modules.apisupport.project
+
+
+ org.netbeans.api.intent
+
+
+ org.netbeans.api.annotations.common
+
+
+
+ 1
+ 1.25
+
+
+
+ org.openide.filesystems
+
+
+
+ 9.1
+
+
+
+ org.openide.util
+
+
+
+ 9.3
+
+
+
+ org.openide.util.lookup
+
+
+
+ 8.26
+
+
+
+
+
+ unit
+
+ org.netbeans.libs.junit4
+
+
+
+ org.netbeans.modules.nbjunit
+
+
+
+
+
+ org.netbeans.api.intent
+ org.netbeans.spi.intent
+
+
+
+
--- a/api.intent/src/org/netbeans/api/intent/Bundle.properties
+++ a/api.intent/src/org/netbeans/api/intent/Bundle.properties
@@ -0,0 +1,7 @@
+OpenIDE-Module-Display-Category=Infrastructure
+OpenIDE-Module-Long-Description=\
+ API for invoking intended operations (described by suitable type of object, e.g. \
+ URI) by some of registered handlers.\n\
+ SPI for handlers of possible intended operations.
+OpenIDE-Module-Name=Intent API
+OpenIDE-Module-Short-Description=Performing intended operations by suitable handlers
--- a/api.intent/src/org/netbeans/api/intent/Callback.java
+++ a/api.intent/src/org/netbeans/api/intent/Callback.java
@@ -0,0 +1,72 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright 2014 Oracle and/or its affiliates. All rights reserved.
+ *
+ * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
+ * Other names may be trademarks of their respective owners.
+ *
+ * The contents of this file are subject to the terms of either the GNU
+ * General Public License Version 2 only ("GPL") or the Common
+ * Development and Distribution License("CDDL") (collectively, the
+ * "License"). You may not use this file except in compliance with the
+ * License. You can obtain a copy of the License at
+ * http://www.netbeans.org/cddl-gplv2.html
+ * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
+ * specific language governing permissions and limitations under the
+ * License. When distributing the software, include this License Header
+ * Notice in each file and include the License file at
+ * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the GPL Version 2 section of the License file that
+ * accompanied this code. If applicable, add the following below the
+ * License Header, with the fields enclosed by brackets [] replaced by
+ * your own identifying information:
+ * "Portions Copyrighted [year] [name of copyright owner]"
+ *
+ * If you wish your version of this file to be governed by only the CDDL
+ * or only the GPL Version 2, indicate your decision by adding
+ * "[Contributor] elects to include this software in this distribution
+ * under the [CDDL or GPL Version 2] license." If you do not indicate a
+ * single choice of license, a recipient has the option to distribute
+ * your version of this file under either the CDDL, the GPL Version 2 or
+ * to extend the choice of license to its licensees as provided above.
+ * However, if you add GPL Version 2 code and therefore, elected the GPL
+ * Version 2 license, then the option applies only if the new code is
+ * made subject to such option by the copyright holder.
+ *
+ * Contributor(s):
+ *
+ * Portions Copyrighted 2014 Sun Microsystems, Inc.
+ */
+package org.netbeans.api.intent;
+
+import org.netbeans.api.annotations.common.NonNull;
+import org.netbeans.api.annotations.common.NullAllowed;
+
+/**
+ * Callback invoked when an intent action has finished. It is run in a dedicated
+ * thread in background.
+ *
+ * @see Intent#execute(org.netbeans.api.intent.Callback)
+ *
+ * @author jhavlin
+ */
+public interface Callback {
+
+ /**
+ * Invoked when the intent action has completed successfully. The type of
+ * result depends on implementation of chosen intent handler, it can be
+ * null.
+ *
+ * @param result Result value.
+ */
+ public void success(@NullAllowed Object result);
+
+ /**
+ * Invoked when the intent action has failed.
+ *
+ * @param exception Encountered exception.
+ */
+ public void failure(@NonNull Exception exception);
+}
--- a/api.intent/src/org/netbeans/api/intent/Intent.java
+++ a/api.intent/src/org/netbeans/api/intent/Intent.java
@@ -0,0 +1,290 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright 2014 Oracle and/or its affiliates. All rights reserved.
+ *
+ * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
+ * Other names may be trademarks of their respective owners.
+ *
+ * The contents of this file are subject to the terms of either the GNU
+ * General Public License Version 2 only ("GPL") or the Common
+ * Development and Distribution License("CDDL") (collectively, the
+ * "License"). You may not use this file except in compliance with the
+ * License. You can obtain a copy of the License at
+ * http://www.netbeans.org/cddl-gplv2.html
+ * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
+ * specific language governing permissions and limitations under the
+ * License. When distributing the software, include this License Header
+ * Notice in each file and include the License file at
+ * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the GPL Version 2 section of the License file that
+ * accompanied this code. If applicable, add the following below the
+ * License Header, with the fields enclosed by brackets [] replaced by
+ * your own identifying information:
+ * "Portions Copyrighted [year] [name of copyright owner]"
+ *
+ * If you wish your version of this file to be governed by only the CDDL
+ * or only the GPL Version 2, indicate your decision by adding
+ * "[Contributor] elects to include this software in this distribution
+ * under the [CDDL or GPL Version 2] license." If you do not indicate a
+ * single choice of license, a recipient has the option to distribute
+ * your version of this file under either the CDDL, the GPL Version 2 or
+ * to extend the choice of license to its licensees as provided above.
+ * However, if you add GPL Version 2 code and therefore, elected the GPL
+ * Version 2 license, then the option applies only if the new code is
+ * made subject to such option by the copyright holder.
+ *
+ * Contributor(s):
+ *
+ * Portions Copyrighted 2014 Sun Microsystems, Inc.
+ */
+package org.netbeans.api.intent;
+
+import java.net.URI;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+import java.util.SortedSet;
+import java.util.TreeSet;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Future;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import java.util.regex.Pattern;
+import org.netbeans.api.annotations.common.NonNull;
+import org.netbeans.api.annotations.common.NullAllowed;
+import org.netbeans.modules.intent.CallbackResult;
+import org.netbeans.modules.intent.IntentHandler;
+import org.netbeans.modules.intent.SettableResult;
+import org.netbeans.spi.intent.Result;
+import org.openide.filesystems.FileObject;
+import org.openide.filesystems.FileUtil;
+import org.openide.util.Parameters;
+
+/**
+ * Description of some intended operation. The operation is described by an
+ * action and a URI.
+ *
+ *
+ * If the intent is executed, proper registered handler is chosen to perform the
+ * actual operation.
+ *
+ *
+ * For example, the following code can be used to open a file in editor (if the
+ * environment is suitable for such operation).
+ *
+ *
+ * new Intent(Intent.ACTION_VIEW, new URI("file://path/file.txt")).execute();
+ *
+ *
+ * @author jhavlin
+ */
+public final class Intent {
+
+ private static final Logger LOG = Logger.getLogger(Intent.class.getName());
+
+ /**
+ * Standard VIEW action type.
+ */
+ public static final String ACTION_VIEW = "VIEW"; //NOI18N
+
+ /**
+ * Standard EDIT action type.
+ */
+ public static final String ACTION_EDIT = "EDIT"; //NOI18N
+
+ private final String action;
+ private final URI uri;
+
+ /**
+ * Constructor for an intended operation.
+ *
+ * @param action Action type to perform. It is recommended to use either
+ * standard actions predefined in Intent class (see {@link #ACTION_EDIT},
+ * {@link #ACTION_VIEW}), or strings similar to fully qualified field names
+ * (e.g. "org.some.package.ClassName.ACTION_CUSTOM").
+ *
+ * @param uri URI specifying the operation.
+ */
+ public Intent(@NonNull String action, @NonNull URI uri) {
+ Parameters.notNull("action", action);
+ Parameters.notNull("uri", uri);
+ this.action = action;
+ this.uri = uri;
+ }
+
+ /**
+ * Get action type.
+ *
+ * @return The action type.
+ */
+ public @NonNull String getAction() {
+ return action;
+ }
+
+ /**
+ * Get URI specifying this intent.
+ *
+ * @return The URI.
+ */
+ public @NonNull URI getUri() {
+ return uri;
+ }
+
+ /**
+ * Execute the intent. The operation will be run asynchronously.
+ *
+ * If the result is ignored, it's recommended to use
+ * {@code intent.execute(null);}
+ *
+ *
+ * @return {@link Future} Future for result of the action. The type of
+ * result depends on implementation of chosen intent handler, it can be
+ * null.
+ */
+ public @NonNull Future