Skip to content

Commit 0e4ac38

Browse files
ctruedenclaude
andcommitted
scijava-command: discoverable commands, and the metadata menus need
A command is a Runnable with declared parameters, discovered with @plugin(type = Command.class) and placed in the menus with a stacked @menu. Keeping those separate is what stops @plugin accumulating attributes that make no sense for most plugin types -- a converter has no menu path -- while leaving @plugin the single uniform way to declare a plugin, so "is a command a plugin?" still answers yes. Stacking needed no new indexing machinery: the processor indexes anything meta-annotated @indexable, one file per annotation, so @menu gets its own index and Commands.discover joins the two on the class name. No bytecode parser, and no class loading -- a test asserts a menu is built with path, label, accelerator, icon, weight and visibility while constructing nothing. CommandInfo implements Executable, so a discovered command reaches the runner and the processors by the same path a script does; the script-shaped test in scijava-execute shares that path. "Command" here means what SciJava Common called a module: anything runnable with declared parameters. A script is a command whose implementation is source in some language. Module is retired, Java having taken the word. Two things worth noting: - A command's package must be opened to two modules: the context constructs the command and the execution layer reads its @parameter fields. Whether to consolidate that is recorded as an open question, since it is a line many people will have to write. - The "menus construct nothing" assertion first used a static flag on a command another test runs, and JUnit does not order methods by declaration, so it passed or failed by luck. It now asserts against a command no test runs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 0138735 commit 0e4ac38

12 files changed

Lines changed: 1063 additions & 0 deletions

File tree

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
<!-- End implicit dependencies -->
5959

6060
<module>scijava-collections</module>
61+
<module>scijava-command</module>
6162
<module>scijava-common3</module>
6263
<module>scijava-context</module>
6364
<module>scijava-context-test</module>

‎scijava-command/pom.xml‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.scijava</groupId>
7+
<artifactId>pom-scijava</artifactId>
8+
<version>44.0.0</version>
9+
<relativePath />
10+
</parent>
11+
12+
<artifactId>scijava-command</artifactId>
13+
<version>1.0.0-SNAPSHOT</version>
14+
15+
<name>SciJava Command</name>
16+
<description>Discoverable commands, with the metadata a menu is built from.</description>
17+
<url>https://github.com/scijava/scijava</url>
18+
<inceptionYear>2026</inceptionYear>
19+
<organization>
20+
<name>SciJava</name>
21+
<url>https://scijava.org/</url>
22+
</organization>
23+
<licenses>
24+
<license>
25+
<name>Simplified BSD License</name>
26+
<distribution>repo</distribution>
27+
</license>
28+
</licenses>
29+
30+
<developers>
31+
<developer>
32+
<id>ctrueden</id>
33+
<name>Curtis Rueden</name>
34+
<roles>
35+
<role>founder</role>
36+
<role>lead</role>
37+
<role>reviewer</role>
38+
<role>support</role>
39+
<role>maintainer</role>
40+
</roles>
41+
</developer>
42+
<developer>
43+
<id>gselzer</id>
44+
<name>Gabriel Selzer</name>
45+
<roles>
46+
<role>founder</role>
47+
<role>debugger</role>
48+
<role>reviewer</role>
49+
<role>support</role>
50+
</roles>
51+
</developer>
52+
</developers>
53+
<contributors>
54+
<contributor>
55+
<name>Johannes Schindelin</name>
56+
<properties><id>dscho</id></properties>
57+
</contributor>
58+
</contributors>
59+
60+
<mailingLists>
61+
<mailingList>
62+
<name>Image.sc Forum</name>
63+
<archive>https://forum.image.sc/tag/scijava</archive>
64+
</mailingList>
65+
</mailingLists>
66+
67+
<scm>
68+
<connection>scm:git:https://github.com/scijava/scijava</connection>
69+
<developerConnection>scm:git:git@github.com:scijava/scijava</developerConnection>
70+
<tag>HEAD</tag>
71+
<url>https://github.com/scijava/scijava</url>
72+
</scm>
73+
<issueManagement>
74+
<system>GitHub Issues</system>
75+
<url>https://github.com/scijava/scijava/issues</url>
76+
</issueManagement>
77+
<ciManagement>
78+
<system>GitHub Actions</system>
79+
<url>https://github.com/scijava/scijava/actions</url>
80+
</ciManagement>
81+
82+
<properties>
83+
<package-name>org.scijava.command</package-name>
84+
85+
<license.licenseName>bsd_2</license.licenseName>
86+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
87+
88+
<!-- Note: These versions must match across all component POMs! -->
89+
<scijava-context.version>1.0.0-SNAPSHOT</scijava-context.version>
90+
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
91+
<scijava-execute.version>1.0.0-SNAPSHOT</scijava-execute.version>
92+
<scijava-index.version>1.0.0-SNAPSHOT</scijava-index.version>
93+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
94+
<scijava-struct.version>1.0.1-SNAPSHOT</scijava-struct.version>
95+
</properties>
96+
97+
<dependencies>
98+
<dependency>
99+
<groupId>org.scijava</groupId>
100+
<artifactId>scijava-context</artifactId>
101+
<version>${scijava-context.version}</version>
102+
</dependency>
103+
<dependency>
104+
<groupId>org.scijava</groupId>
105+
<artifactId>scijava-discovery</artifactId>
106+
<version>${scijava-discovery.version}</version>
107+
</dependency>
108+
<dependency>
109+
<groupId>org.scijava</groupId>
110+
<artifactId>scijava-execute</artifactId>
111+
<version>${scijava-execute.version}</version>
112+
</dependency>
113+
<dependency>
114+
<groupId>org.scijava</groupId>
115+
<artifactId>scijava-index</artifactId>
116+
<version>${scijava-index.version}</version>
117+
</dependency>
118+
<dependency>
119+
<groupId>org.scijava</groupId>
120+
<artifactId>scijava-priority</artifactId>
121+
<version>${scijava-priority.version}</version>
122+
</dependency>
123+
<dependency>
124+
<groupId>org.scijava</groupId>
125+
<artifactId>scijava-struct</artifactId>
126+
<version>${scijava-struct.version}</version>
127+
</dependency>
128+
129+
<!-- Test scope dependencies -->
130+
<dependency>
131+
<groupId>org.junit.jupiter</groupId>
132+
<artifactId>junit-jupiter-api</artifactId>
133+
<scope>test</scope>
134+
</dependency>
135+
</dependencies>
136+
137+
<build>
138+
<plugins>
139+
<!--
140+
NB: the annotation index comes from scijava-index's annotation
141+
processor, which must be on the processor path: javac will not find
142+
it on the module path, and says nothing when it finds no processor at
143+
all, so the build would simply produce no index.
144+
-->
145+
<plugin>
146+
<artifactId>maven-compiler-plugin</artifactId>
147+
<configuration>
148+
<annotationProcessorPaths>
149+
<path>
150+
<groupId>org.scijava</groupId>
151+
<artifactId>scijava-index</artifactId>
152+
<version>${scijava-index.version}</version>
153+
</path>
154+
</annotationProcessorPaths>
155+
</configuration>
156+
</plugin>
157+
<plugin>
158+
<artifactId>maven-enforcer-plugin</artifactId>
159+
<executions>
160+
<execution>
161+
<id>enforce-package-rules</id>
162+
<goals>
163+
<goal>enforce</goal>
164+
</goals>
165+
<phase>test</phase>
166+
<configuration>
167+
<rules>
168+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
169+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
170+
</rules>
171+
</configuration>
172+
</execution>
173+
</executions>
174+
</plugin>
175+
<plugin>
176+
<artifactId>maven-javadoc-plugin</artifactId>
177+
<configuration>
178+
<links>
179+
<link>https://javadoc.scijava.org/Java11/</link>
180+
</links>
181+
</configuration>
182+
</plugin>
183+
</plugins>
184+
</build>
185+
</project>
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/*
2+
* #%L
3+
* Discoverable commands, with the metadata a menu is built from.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
module org.scijava.command {
31+
32+
exports org.scijava.command;
33+
34+
// NB: a command's package must be opened to both modules that reflect into
35+
// it: the context constructs the command, and the execution layer reads and
36+
// writes its @Parameter fields. `opens` is not `exports` -- the classes stay
37+
// invisible to ordinary callers either way.
38+
opens org.scijava.command to org.scijava.context, org.scijava.execute;
39+
40+
requires transitive org.scijava.context;
41+
requires transitive org.scijava.execute;
42+
requires transitive org.scijava.struct;
43+
requires org.scijava.discovery;
44+
requires org.scijava.index;
45+
requires org.scijava.priority;
46+
47+
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/*
2+
* #%L
3+
* Discoverable commands, with the metadata a menu is built from.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.command;
31+
32+
/**
33+
* Something a user can run: the unit a menu item, a script and a recorded
34+
* step all refer to.
35+
* <p>
36+
* A Java command is a class implementing this interface, declaring its
37+
* parameters as {@code org.scijava.execute.Parameter} fields, and declaring
38+
* itself with {@code @Plugin(type = Command.class)}:
39+
* </p>
40+
*
41+
* <pre>
42+
* &#64;Plugin(type = Command.class)
43+
* &#64;Menu(path = "Image&gt;Adjust&gt;Brightness/Contrast...", weight = 12)
44+
* public class BrightnessContrast implements Command {
45+
*
46+
* &#64;Parameter
47+
* private Dataset image;
48+
*
49+
* public void run() { ... }
50+
* }
51+
* </pre>
52+
* <h2>On the word</h2>
53+
* <p>
54+
* "Command" here means what SciJava Common called a <em>module</em>: anything
55+
* runnable with declared parameters. A script is a command whose
56+
* implementation is source in some language; a class like the one above is a
57+
* command whose implementation is Java. Neither is a special case of the
58+
* other, and both reach the menu, the harvester and the runner by one path -
59+
* see {@code org.scijava.execute.Executable}, which mentions no Java
60+
* reflection at all.
61+
* </p>
62+
* <p>
63+
* The old vocabulary is retired: <em>module</em> now means a JPMS module,
64+
* <em>macro</em> means the ImageJ 1.x macro language and nothing here, and
65+
* <em>extension</em> is not a technical term.
66+
* </p>
67+
*
68+
* @author Curtis Rueden
69+
*/
70+
public interface Command extends Runnable {
71+
// NB: no methods of its own. A command is a Runnable that declares
72+
// parameters, and the parameters are declared by annotation.
73+
}

0 commit comments

Comments
 (0)