## page was renamed from Cytoscape_3.0/CommandDiscussions
<<TableOfContents>>

== Command Layer Definition ==

Command layer contains mechanism to make Cytoscape functions easily accessible from application layer.  This layer should be separated from application layer and can be used in any mode: Desktop application, server version, and command line version.   

== Requirements ==
 * Command layer should be separated from application or UI.
 * Commands should be accessible from scripting (dynamic) languages.
 * Command history should be manageable by Undo manager (in application layer).
 * Extensible.  Plugin writers and developers use Cytoscape as library can add their own commands. 
 * Developers can chain commands to develop a workflow, like UNIX shell piping.

=== Command Usecases ===
(Not finished yet...)


=== Multiple Language Support ===
Commands should be easily accessible from dynamic (scripting) languages, including Python, Ruby, and JavaScript.  This will be implemented using scripting language engins running on JVM (Jruby, Rhino, and Jython).  This enables users to write simple tasks as scripts.


=== Functions Encapsulated as Command ===
In general, most of the classes in '''''cytoscape.actions''''' will be converted into Commands.  In addition, some of the methods under the class ''cytoscape.Cytoscape'' will be encapsulated as command.  Such as:

 * createNetwork()
 * createNewSession()
 * getNetwork()
 
== Design ==

 {{attachment:commandLayer1.png}}

 * Each command will be registered as an '''''OSGi service'''''.
 * Users (developers) access commands through the '''''OSGi ServiceTracker'''''.
 * For easy access to commands, an utility class '''''CommandServiceManager''''' will be implemented.  This is a wrapper class for OSGi !ServiceTracker.

=== How to Call Commands ===
{{{#!java
// Java
Command c = CommandService.getCommand("command_name");
Object result = c.execute( parameters );

// Ruby
c = CommandService.getCommand("command_name")
result = c.execute( parameters )

}}}

We can implement similar functions Felix ShellService has:

{{{#!java
package org.apache.felix.shell;

public interface ShellService
{
    public String[] getCommands();
    public String getCommandUsage(String name);
    public String getCommandDescription(String name);
    public ServiceReference getCommandReference(String name);
    public void executeCommand(
        String commandLine, PrintStream out, PrintStream err)
        throws Exception;
}
}}}

Like other layers, Command Layer will be distributed as a bundle.  This bundle consists of the following:

 1. Command interface: All commands should implement this interface.
 1. Command Service Manager: (will be discussed in the next section)

Because Command implementations will be services, any bundle (or plugin) will be able to make Command services available.  There will likely be a one or two bundles that provide the bulk to the Commands that constitute the core of Cytoscape including Command like loadNetwork(), etc..  Any plugin writing a command will depend on the Command bundle.

=== Command Service Manager ===
''Command Service Manager'' is a simple utility class to make all commands easily accessible from all parts of Cytoscape.  Essentially, this is a custom version of '''''ServiceTracker''''' class.  Since all commands are registered as OSGi services, command users access commands through OSGi service mechanism.  However, it is better to wrap this with a simple API to hide the detail of the OSGi service mechanism.  The CommandServiceManager API will be something like the following:

{{{#!java
public class CommandServiceManager {
    public static Command getCommand(String command_name) {}
    public static List<String> getAvailableCommand() {}
}
}}} 

This class is only for accessing (using) commands.  Developers should register command implementations like other OSGi services (can be done with Spring-DM).  Each command have a '''''OSGi Service Property''''' to represent that it is a Cytoscape command.  This property will be used by the service tracker to filtering services.

== Implementation ==

All commands should implement the following interface:
{{{#!java
public interface Command {
	// Getters
	public String getName();
	public String getDescription();

       // support for Tunables here...

	// Execute the command.
	public void execute() throws Exception;
}
}}}

Because Commands will all require different inputs to function there is no way to capture this using a single interface. For example, a ''LayoutNetworkView'' command will need two parameters a ''LayoutAlgorithm'' and a ''NetworkView'' to operate.  Rather than configuring the Command interface to support networks and layout algorithms, we need a general mechanism for specifying input parameters. We propose that Tunables will be the mechanism for specifying Command parameters.   
In 2.6, '''''Tunable''''' was a class that stores parameter values and provides mechanisms for a user interface to be inferred from the parameter value.  Tunables will be refactored in version 3.0 to address a few design deficiencies. Tunables are discussed extensively [[Cytoscape 3.0/TunableDiscussion here]].  Whatever the final Tunable mechanism looks like, this is what we will use for specifying parameters to Commands.


==== Open Questions ====
 * How the events are handled?
    * Commands should likely define and fire their own events as appropriate.  For instance a LoadNetwork Command will fire a LoadNetworkEvent that LoadNetworkListeners will listen for.  See the [[Cytoscape 3.0/ModelDiscussion]] page for elaboration on events.
 * How will Commands validate arguments?  
    * Just like normal. Actual implementation of the Command looks like the following.  Validation of the arguments are command writer's responsibility.  Tunable-based setting and getting are type-safe, but do not include range checkers for primitive types.  These values

    {{{#!java
public class ImportGraphFileCommand extends AbstractCommand {

	@Tunable(description = "Location of the network file to be imported.", required = true)
	private URI fileLocation;

	public void execute() throws Exception {
		if(validate()) {
			// execute the command
		} else {
			// Throw invalid argument exception
		}
	}
	
	private boolean validate() {
		// Check required fields and value ranges here.
		return true;
	}
}
    }}}

=== Commands with Dependency Injection Framework ===
With Spring Framework, the command layer will looks like the following:
 * Injecting name and description.
   {{{
	<context:annotation-config />
	
	<context:component-scan
		base-package="org.cytoscape.command.internal" />

	<!-- Inject command properties -->
	<bean id="importGraphFileCommand"
		class="org.cytoscape.command.internal.ImportGraphFileCommand">
		<property name="name" value="importGraphFileCommand" />
		<property name="description" value="Load network file." />
	</bean>
   }}}
 * Export the command as OSGi service
   {{{
<osgi:service id="importGraphFileCommandOSGiService" auto-export="interfaces" ref="importGraphFileCommand" />
   }}}

One of the advantages to use DI container is simpler integration test code.

{{{#!java
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations={"/META-INF/spring/bundle-context.xml"})
public class ExampleBeanIntegrationTest extends
		AbstractDependencyInjectionSpringContextTests {
	
	@Autowired
	private ImportGraphFileCommand command1;

	@Autowired
	private LayoutCommand command2;

        ...

        @Test
	public void testWorkflow() throws Exception {
		List<Object> parameter = new ArrayList<Object>();
		List<Class<?>> parameterType = new ArrayList<Class<?>>();
		
		parameter.add("testData/galFiltered.sif");
		parameterType.add(String.class);
		
		List<Object> result = command1.execute(parameter, parameterType);
		
		//Do something with other commands
		
	}
}
}}}

===== Commad Implemented with Dynamic Languages =====
From Spring 2.5, it has a [[http://static.springframework.org/spring/docs/2.5.x/reference/dynamic-language.html|built-in support for dynamic languages]].  By using this feature, developers can implement commands with other languages and make it available other developers.

 * RubyCommand.rb
   {{{#!ruby
require 'java'

class RubyCommand
	include org.cytoscape.command3.Command
	
	# Command detail
	
end
   }}}
 * Spring configuration file
   {{{
	<lang:jruby id="rubyService"
		script-interfaces="org.cytoscape.command3.Command"
		script-source="classpath:RubyCommand.rb">
		<lang:property name="name" value="Command implemented by ruby." />
	</lang:jruby>
   }}}



And Command Service Manager will be a class that holds an OSGi ServiceTracker:

{{{#!java
public final class CommandManager implements BundleActivator {

	private ServiceTracker commandServiceTracker;

        public Command getCommand(final String commandName){
            //returns the command using Service Tracker
        }

	public void start(BundleContext bundleContext) throws Exception {
		commandServiceTracker = new ServiceTracker(bundleContext, Command.class
				.getName(), null) {
			@Override
			public Command addingService(ServiceReference serviceReference) {
			        Command command = (Command) super.addingService(serviceReference);
				return command;
			}
		};

		commandServiceTracker.open();
		
	}

	public void stop(BundleContext bundleContext) throws Exception {
		commandServiceTracker.close();
	}
}
}}}

== References and External Links ==

=== OSGi Service ===
 * [[http://neilbartlett.name/downloads/preview_intro_services.pdf|Introduction to Services]]
 * [[http://www.knopflerfish.org/osgi_service_tutorial.html|OSGi Service Tutorial]]

 * [[http://felix.apache.org/site/apache-felix-shell-service.html|Felix ShellService]]

=== Frameworks ===
 * [[http://www.springframework.org/|Spring Framework]]
 * [[http://www.springframework.org/osgi|Spring-DM]]

=== Dynamic Language Support on JVM ===
 * [[http://www.jython.org/Project/index.html|Jython]]
 * [[http://jruby.codehaus.org/|JRuby]]
 * [[http://www.mozilla.org/rhino/|Rhino (JavaScript)]]