Revision 6844
Added by Matt Jones about 12 years ago
submitting.rst | ||
---|---|---|
792 | 792 |
Using the EarthGrid API (aka EcoGrid) |
793 | 793 |
------------------------------------- |
794 | 794 |
|
795 |
.. Note:: |
|
796 |
|
|
797 |
The EarthGrid/EcoGrid web service API is *deprecated* and will be removed from |
|
798 |
a future version of Metacat. Its functionality is being replaced by the |
|
799 |
standardized DataONE REST service interface. |
|
800 |
|
|
801 |
The EarthGrid (aka EcoGrid) provides access to disparate data on different |
|
802 |
networks (e.g., KNB, GBIF, GEON) and storage systems (e.g., Metacat and SRB), |
|
803 |
allowing scientists access to a wide variety of data and analytic resources |
|
804 |
(e.g., data, metadata, analytic workflows and processors) networked at different |
|
805 |
sites and at different organizations via the internet. |
|
806 |
|
|
807 |
Because Metacat supports the EarthGrid API (see table), it can query the |
|
808 |
distributed EarthGrid, retrieve metadata and data results, and write new and |
|
809 |
updated metadata and data back to the grid nodes. |
|
810 |
|
|
811 |
For more information about each EarthGrid service and its WSDL file, navigate |
|
812 |
to the "services" page on your Metacat server |
|
813 |
(e.g., http://knb.ecoinformatics.org/knb/services). |
|
814 |
Note that the AdminService and Version service that appear on this page are |
|
815 |
not part of EarthGrid. |
|
816 |
|
|
817 |
EarthGrid/EcoGrid API Summary |
|
818 |
|
|
819 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
820 |
| Service | Description | |
|
821 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
822 |
| AuthenticationQueryService | Search for and retrieve protected metadata and data from the EarthGrid as an authenticated user. | |
|
823 |
| | | |
|
824 |
| | Methods: ``query``, ``get`` | |
|
825 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
826 |
| AuthenticationService | Log in and out of the EarthGrid | |
|
827 |
| | | |
|
828 |
| | Methods: ``login``, ``logout`` | |
|
829 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
830 |
| IdentifierService | List, lookup, validate, and add Life Science Identifiers (LSIDs) to the EarthGrid | |
|
831 |
| | | |
|
832 |
| | Methods: ``isRegistered``, ``addLSID``, ``getNextRevision``, ``getNextObject``, ``getAllIds`` | |
|
833 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
834 |
| PutService | Write metadata to the EarthGrid | |
|
835 |
| | | |
|
836 |
| | Methods: ``put`` | |
|
837 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
838 |
| QueryService | Search for and retrieve metadata from the EarthGrid | |
|
839 |
| | | |
|
840 |
| | Methods: ``query``, ``get`` | |
|
841 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
842 |
| RegistryService | Add, update, remove, and search for registered EarthGrid services. | |
|
843 |
| | Note: The WSDL for this service is found under http://ecogrid.ecoinformatics.org/registry/services | |
|
844 |
| | | |
|
845 |
| | Methods: ``add``, ``update``, ``remove``, ``list``, ``query`` | |
|
846 |
+----------------------------+-----------------------------------------------------------------------------------------------------+ |
|
847 |
|
|
795 | 848 |
Using Morpho |
796 | 849 |
------------ |
850 |
Morpho is a desktop tool created to facilitate the creation, storage, and |
|
851 |
retrieval of metadata. Morpho interfaces with any Metacat server, allowing |
|
852 |
users to upload, download, store, query and view relevant metadata and data |
|
853 |
using the network. Users can authorize the public or only selected colleagues |
|
854 |
to view their data files. |
|
797 | 855 |
|
856 |
Morpho is part of the Knowledge Network for Biocomplexity (KNB), a national |
|
857 |
network intended to facilitate ecological and environmental research on |
|
858 |
biocomplexity. To use Morpho with your Metacat, set the Metacat URL in the |
|
859 |
Morpho Preferences to point to your Metacat server. |
|
860 |
|
|
861 |
.. figure:: images/screenshots/image049.png |
|
862 |
:align: center |
|
863 |
|
|
864 |
Set the Metacat URL in the Morpho preferences to point to your Metacat. |
|
865 |
|
|
866 |
For more information about Morpho, please see: http://knb.ecoinformatics.org/morphoportal.jsp |
|
867 |
|
|
798 | 868 |
Creating Your Own Client |
799 | 869 |
------------------------ |
870 |
Metacat's client API is available in Java and Perl (the Java interface is |
|
871 |
described in this section and further detailed in the appendix). Some of the |
|
872 |
API is also available in Python and Ruby. The API allows client applications |
|
873 |
to easily authenticate users and perform basic Metacat operations such as |
|
874 |
reading metadata and data files; inserting, updating, and deleting files; and |
|
875 |
searching for packages based on metadata matches. |
|
800 | 876 |
|
877 |
The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat, |
|
878 |
and all operations are fully defined in the javadoc_ documentation. To use the |
|
879 |
client API, include the ``metacat-client.jar``, ``utilities.jar``, and |
|
880 |
``httpclient.jar`` in your classpath. After including these classes, you can |
|
881 |
begin using the API methods (see the next table). |
|
882 |
|
|
883 |
.. _javadoc: http://knb.ecoinformatics.org/software/metacat/dev/api/index.html |
|
884 |
|
|
885 |
The following code block displays a typical session for reading a document |
|
886 |
from Metacat using the Java client API. |
|
887 |
|
|
888 |
:: |
|
889 |
|
|
890 |
String metacatUrl = "http://foo.com/context/metacat"; |
|
891 |
String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org"; |
|
892 |
String password = "neverHarcodeAPasswordInCode"; |
|
893 |
try { |
|
894 |
Metacat m = MetacatFactory.createMetacatConnection(metacatUrl); |
|
895 |
m.login(username, password); |
|
896 |
Reader r = m.read("testdocument.1.1"); |
|
897 |
// Do whatever you want with Reader r |
|
898 |
} catch (MetacatAuthException mae) { |
|
899 |
handleError("Authorization failed:\n" + mae.getMessage()); |
|
900 |
} catch (MetacatInaccessibleException mie) { |
|
901 |
handleError("Metacat Inaccessible:\n" + mie.getMessage()); |
|
902 |
} catch (Exception e) { |
|
903 |
handleError("General exception:\n" + e.getMessage()); |
|
904 |
} |
|
905 |
|
|
906 |
Operations provided by Client API (Metacat.java class) |
|
907 |
|
|
908 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
909 |
| Method | Parameters and Throws | Description | |
|
910 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
911 |
| delete | ``public String delete(String docid) throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Delete an XML document in the repository. | |
|
912 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
913 |
| getAllDocids | ``public Vector getAllDocids(String scope) throws MetacatException;`` | Return a list of all docids that match a given scope. If scope is null, return all docids registered in the system. | |
|
914 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
915 |
| getLastDocid | ``public String getLastDocid(String scope) throws MetacatException;`` | Return the highest document ID for a given scope. Used by clients to determine the next free identifier in a sequence for a given scope. | |
|
916 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
917 |
| getloggedinuserinfo | ``public String getloggedinuserinfo() throws MetacatInaccessibleException;`` | Return the logged in user for this session. | |
|
918 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
919 |
| getNewestDocRevision | ``public int getNewestDocRevision(String docId) throws MetacatException;`` | Return the latest revision of specified the document from Metacat | |
|
920 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
921 |
| getSessonId | ``public String getSessionId();`` | Return the session identifier for this session. | |
|
922 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
923 |
| insert | ``public String insert(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Insert an XML document into the repository. | |
|
924 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
925 |
| isRegistered | ``public boolean isRegistered(String docid) throws MetacatException;`` | Return true if given docid is registered; false if not. | |
|
926 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
927 |
| login | ``public String login(String username, String password) throws MetacatAuthException, MetacatInaccessibleException;`` | Log in to a Metacat server. | |
|
928 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
929 |
| logout | ``public String logout() throws MetacatInaccessibleException, MetacatException;`` | Log out of a Metacat server. | |
|
930 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
931 |
| query | ``public Reader query(Reader xmlQuery) throws MetacatInaccessibleException, IOException;`` | Query the Metacat repository and return the result set as a Reader. | |
|
932 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
933 |
| query | ``public Reader query(Reader xmlQuery, String qformat) throws MetacatInaccessibleException, IOException;`` | Query the Metacat repository with the given metacat-compatible query format and return the result set as a Reader. | |
|
934 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
935 |
| read | ``public Reader read(String docid) throws InsufficientKarmaException, MetacatInaccessibleException, DocumentNotFoundException, MetacatException;`` | Read an XML document from the Metacat server. | |
|
936 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
937 |
| readInlineData | ``public Reader readInlineData(String inlinedataid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;`` | Read inline data from the Metacat server session. | |
|
938 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
939 |
| setAccess | ``public String setAccess(String _docid, String _principal, String _permission, String _permType, String _permOrder ); throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;`` | Set permissions for an XML document in the Metacat repository. | |
|
940 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
941 |
| setMetacatUrl | ``public void setMetacatUrl(String metacatUrl);`` | Set the MetacatUrl to which connections should be made. | |
|
942 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
943 |
| setSessionId | ``public void setSessionId(String sessionId);`` | Set the session identifier for this session. | |
|
944 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
945 |
| update | ``public String update(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Update an XML document in the repository by providing a new version of the XML document. | |
|
946 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
947 |
| upload | ``public String upload(String docid, File file) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. | |
|
948 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
949 |
| upload | ``public String publicupload(String docid, String fileName, InputStream fileData, int size) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;`` | Upload a data document into the repository. | |
|
950 |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ |
|
951 |
|
Also available in: Unified diff
Completed 'Submission' page conversion, and also converted GeoServer docs to
RST format.