Skip to content
This repository was archived by the owner on Jan 9, 2023. It is now read-only.

The Command Line Access

Jump to bottom
Anonymous edited this page Sep 10, 2015 · 16 revisions

The functionality in the core module is accessible via a command line too, with pretty much a 1-1 mapping between the methods in the managers and line commands.

##Obtaining the command line binary If you don't want to build the command line package from the sources and the Maven project, you can just download it from here and skip the next paragraph.

##Building the command line binary if, instead, you want to build a fresh binary from the sources, obtain them as explained here, and follow building instructions. Issuing 'mvn package' or 'mvn install' from the root level of the myEquivalents source package should build the command line .zip, which is put under myequivalents-cmdline/target/myequivalents_shell_*.zip.

##Installing and configuring from the binary .zip Once you explode the command line .zip binary, you'll have the myeq.sh, the starting point for all the myequivalents functionality. This depends on myequivalents_deps.jar, which should be kept in the same directory, as well as on other configuration files, such as myeq-manager-config.xml.

As explained in the configuration documentation, you should edit such metadata file to define a proper mean to access the a myEquivalents back end, such as the relational database or the web service. By default, the command line is configured with the relational database backend and the H2 database.

###Configuration and Java classpath The command line binary is shipped with the .jar for the relational backend (myequivalents-db-XXX.jar) and the JDBC driver for the HSQL database. If you want to use other access means for myEquivalents (i.e., the web service), or another relational database (e.g., Oracle), you must either rebuild from the sources, by changing the Maven pom file and setting up proper dependencies (typically you set these in a new Maven profile), or you need to pass a proper Java class path to your command line invocation. That can be done by setting the shell environment variable CLASSPATH, see here and the myeq.sh script for details.

###Populating an empty database from the first administrator user In order to be able to edit information in myEquivalents, such as services and entity mappings, you need to have an editor account in its back end, which, in turn, can only be created by an administrator, as any user account. In order to be able to break this loop, the '--first-user' can be used together with the command 'user store', to create a first administrator user, bypassing any security control that normal apply to the myEquivalents infrastructure:

10:48:25 $ ./myeq.sh user store --first-user <examples/admin_user.xml
10:48:27.457 [INFO ]: Loading MyEquivalents's Manager Configuration (myeq-manager-config.xml) from CLASSPATH
10:48:29.748 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification

User Updated

The End. Quitting Java with exit code 0.
Java Finished. Quitting the Shell Too.
10:48:30 $
  • You can start from the admin_user.xml example to define the account data that you need.
  • This command can only be executed when the myEquivalents command line is configured with direct access to the database back end. As said elsewhere, this isn't a security problem, since, if you already have the parameters to write in a relational database, you are already able to violate myEquivalents security at a lower level (i.e., using SQL) and it is assumed those who are granted to use such a kind of back end are trusted users. Despite that, we recommend to use the myEquivalents interfaces and related access control anyway, for this makes things clearer, less error-prone and, in future, it will allow you to track operations provenance.

##Command Line Syntax

Once you have installed and setup the command line package, you can access to the following commands, by using the myeq.sh script. As usually they reflect the myEquivalents managers.

10:37:34 $ ./myeq.sh --help



 *** The MyEquivalents Command Line Interface ***

Command-line access to several functions in the MyEquivalents Infrastructure.

General Syntax:

 myeq.sh <command> [dash options] [further options]

Available Commands (and specific options)

 service store [xml file]
   Creates/Updates service definitions and related entities (service-collections, repositories)
   Reads from the standard input if the file is omitted. See the documentation and tests for the XML format to use.

 service delete name...
   Deletes services, identified by their symbolic names
   WARNING This removes ALL the entities referring to the service!

 service get name...
   Gets service info, services identified by name

 service-collection delete name...
   Deletes service-collections, identified by their symbolic names
   Will generate an error if any of the service is being referred by some other entity.

 service-collection get name...
   Gets service-collection info, service-collection identified by name

 repository delete name...
   Deletes repositories, identified by their symbolic names
   Will generate an error if any of the repository is being referred by some other entity.

 repository get name...
   Gets repository info, repositories identified by name

 mapping store <service:accession|uri>...
   Creates mappings between entities, which have to be listed as pairs of identifiers

 mapping store-bundle <service:accession|uri>...
   Maps all the specified entities together, entities have to be listed as pairs of identifiers

 mapping delete <service:accession|uri>...
   Deletes mappings between entities, which have to be listed as pairs of identifiers

 mapping delete-entity <service:accession|uri>...
   Deletes entities from any mapping they are involved in, entities have to be listed as pairs of identifiers

 mapping get <service:accession|uri>...
   Fetches entity mappings

 service set visibility name...
   Set service visibility.

 repository set visibility name...
   Set repository visibility.

 service-collection set visibility name...
   Set service-collection visibility.

 entity set visibility <service:accession|uri>...
   Set entity visibility.

 user get email
   Gets user details

 user store [xml file]
   Creates/Updates a user definition.
   Reads from the standard input if the file is omitted. See the documentation and tests for the XML format to use.

 user delete email
   Removes the given user (requires admin powers)

 user set role email <viewer|editor|admin>
   Changes the user role (requires admin powers)

Options (to be given after 'command' and before further options):
  -d,--release-date <YYYMMDD[-HHMMSS]>    Release date (visibility commands, see documentation)
  -f,--format <out-format>                The result output format. ** ONLY 'xml' IS SUPPORTED IN
                                          THIS VERSION **
  -h,--help                               Prints this help message
  -p,--public-flag <true|false|null>      Public flag (visibility commands, see documentation)
  -r,--raw                                Returns a raw result, i.e., with just the mappings and no
                                          details about services/service-collections/repositories
  -s,--secret <value>                     API secret (i.e., password), used for common commands (see
                                          documentation)
  -u,--user <email>                       User email to be used to login the myEquivalents
                                          repository
  -w,--password <value>                   User password, needed for
                                          administrative/access-control/user-change operations (see
                                          documentation)
  -x,--cascade                            Cascades the visibility settings to referring elements
                                          (e.g., from services to entitities)
  -y,--first-user                         When issuing 'user store', creates a first user (typically
                                          and admin) in an empty database, bypassing authentication
                                          and permission checking (requires the database backend,
                                          see documentation)

18:48:31.300 [INFO ]: Loading MyEquivalents's Manager Configuration (myeq-manager-config.xml) from CLASSPATH
18:48:33.549 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification

The End. Quitting Java with exit code 1.
Java Finished. Quitting the Shell Too.
10:37:41 $

##Usage examples

Creating or updating a new service

17:23:57 $ ./myeq.sh service store --user editor --secret editor.secret examples/foo_services.xml

The file foo_services.xml contains the same XML-based definitions used in the examples above.

As usually, these data change operations require to send authentication details of an editor user. To store other kind of base entities (repositories, service collections), use the same command and XML format.

Stored service can be inspected with 'service get' (the same type of XML is returned):

17:27:26 $ ./myeq.sh service get 'test.testmain.service6'
17:27:43.789 [INFO ]: Loading MyEquivalents's Manager Configuration (myeq-manager-config.xml) from CLASSPATH
17:27:46.009 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<service-items>
    <repositories/>
    <service-collections/>
    <services>
        <service xsi:type="service" entity-type="testmain.someType1" uri-pattern="http://somewhere.in.the.net/testmain/service6/someType1/${accession}" name="test.testmain.service6" title="A Test Service 6" public-flag="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <description>The Description of a Test Service 6</description>
        </service>
    </services>
</service-items>

Service(s) Fetched

The End. Quitting Java with exit code 0.
Java Finished. Quitting the Shell Too.
17:27:47 $

Here, the service is implicitly fetched by the anonymous user (no --user option given) and a result is returned, since the the requested service has public visibility.

Storing a mapping

This creates two pairs of equivalent entities:

$ ./myeq.sh mapping store --user editor.user --secret editor.secret test.testmain.service6:fooacc1 test.testmain.service8:fooacc2 test.testmain.service8:fooacc3 test.testmain.service7:fooacc4
11:18:15.699 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification

Mapping(s) Updated

The End. Quitting Java with exit code 0.
Java Finished. Quitting the Shell Too.
$

Storing a bundle

This creates a whole set of entities that are equivalent each other:

$ ./myeq.sh mapping store-bundle --user editor.user --secret editor.secret test.testmain.service6:fooacc1 test.testmain.service8:fooacc2 test.testmain.service8:fooacc3
11:13:22.624 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification

Bundle(s) Updated

The End. Quitting Java with exit code 0.
Java Finished. Quitting the Shell Too.
$

Fetching a mapping

$ ./myeq.sh mapping get test.testmain.service6:fooacc1 
11:25:37.149 [WARN ]: HHH000144: hibernate.connection.autocommit = false breaks the EJB3 specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mappings>
    <services>
        <service xsi:type="service" entity-type="testmain.someType7" repository-name="test.testmain.repo1" service-collection-name="test.testmain.serviceColl1" name="test.testmain.service7" title="A Test Service 7" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <description>The Description of a Test Service 7</description>
        </service>
        <service xsi:type="service" entity-type="testmain.someType1" uri-pattern="http://somewhere.in.the.net/testmain/service6/someType1/${accession}" name="test.testmain.service6" title="A Test Service 6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <description>The Description of a Test Service 6</description>
        </service>
        <service xsi:type="service" entity-type="testmain.someType2" name="test.testmain.service8" title="A Test Service 8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <description>The Description of a Test Service 8</description>
        </service>
    </services>
    <repositories>
        <repository name="test.testmain.addedRepo1">
            <description>A test Added Repo 1</description>
        </repository>
        <repository name="test.testmain.repo1">
            <description>A Test Repo 1</description>
        </repository>
    </repositories>
    <service-collections>
        <service-collection name="test.testmain.serviceColl1" title="Added Test SC 1">
            <description>A test Service Collection 1</description>
        </service-collection>
    </service-collections>
    <bundles>
        <bundle>
            <entity xsi:type="entity" accession="fooacc1" service-name="test.testmain.service6" uri="http://somewhere.in.the.net/testmain/service6/someType1/fooacc1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            <entity xsi:type="entity" accession="fooacc3" service-name="test.testmain.service8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            <entity xsi:type="entity" accession="fooacc2" service-name="test.testmain.service8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            <entity xsi:type="entity" accession="fooacc4" service-name="test.testmain.service7" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        </bundle>
    </bundles>
</mappings>

Mapping(s) Fetched

The End. Quitting Java with exit code 0.
Java Finished. Quitting the Shell Too.
$

Using the --raw option, you will get a shorter XML, where the service-related information (i.e., the <service> block on top of the XML above) is omitted.

##Usage examples, access control

Creating new users This should be used after the creation of a first administrator account (see above), to add further users:

18:05:53 [brandizi@poderosaii myequivalents_shell_0.2-SNAPSHOT]$ cat editor_user.xml
<user
  email = 'editor.user' name = 'Editor'
  surname = 'User'
  role = 'EDITOR'
  secret = 'editor.secret'
  password = 'editor.password'>
  <notes>Editor User</notes>
</user>
18:06:01 $ ./myeq.sh user store --user admin --password admin.password editor_user.xml

As a security measure, we recommend to create editor users and use them, rather than administrators, for defining new mapping-related data.

Changing an entity visibility

18:40:14 $ ./myeq.sh entity set visibility --user editor.user --secret editor.secret --public-flag false test.testmain.service6:fooacc1

All visibility-related commands have a similar syntax.

Clone this wiki locally