diff --git a/onc/+util/checkVersion.m b/onc/+util/checkVersion.m new file mode 100644 index 0000000..07a156e --- /dev/null +++ b/onc/+util/checkVersion.m @@ -0,0 +1,33 @@ +function isLatestVersion = checkVersion() + url = 'https://github.com/OceanNetworksCanada/api-matlab-client/releases/latest'; + isLatestVersion = 0; + try + % get latest version + releaseInfo = webread(url); + versionPattern = 'Release (\d+\.\d+\.\d+)'; + version = regexp(releaseInfo, versionPattern, 'tokens', 'once'); + latestVersion = version{1}; + % get local version + librariesVersion = ver; + localVersion ='0.0.0'; + for i = librariesVersion + if strcmp(i.Name,'Ocean Networks Canada API Client Library') + localVersion = i.Version; + break; + end + end + + % compare + if ~strcmp(localVersion, latestVersion) + [oncFolderPath, ~, ~] = fileparts(which('Onc')); + localFilePath = [oncFolderPath '\..\doc\UpdateInstruction.html']; + formattedPath = ['file:///', strrep(localFilePath, '\', '/')]; + link = sprintf('<a href="%s">How to update this library</a>', formattedPath); + warning(['You are using an outdated version(%s) of the library. Update to the latest version(%s) to avoid potential errors. ' ... + 'For instructions on updating to the latest version, please visit: %s'], localVersion, latestVersion, link); + else + isLatestVersion = 1; + end + catch ME + % do nothing + end diff --git a/onc/Contents.m b/onc/Contents.m new file mode 100644 index 0000000..e22a6ae --- /dev/null +++ b/onc/Contents.m @@ -0,0 +1,21 @@ +% Ocean Networks Canada API Client Library +% Version 2.2.0 10-Jun-2024 +% +% Functions +% +onc/OncDiscovery - Contains the functionality that wraps the API discovery services +% +onc/OncDelivery - Contains the functionality that wraps the API data product delivery services. To be inherited by the Onc class +% +onc/OncRealTime - Contains the functionality that wraps API real-time services. +% +onc/OncArchive - Contains the functionality that wraps API archivefile services +% +% Live Scripts +% examples/OncDiscoveryLocations.mat - Example Usage of OncDiscovery Location Service +% examples/OncDiscoveryProperties.mat - Example Usage of OncDiscovery Properties Service +% examples/OncDiscoveryDataProducts.mat - Example Usage of OncDiscovery DataProducts Service +% examples/OncDiscoveryDeployments.mat - Example Usage of OncDiscovery Deployments Service +% examples/OncDiscoveryDeviceCategories.mat - Example Usage of OncDiscovery Device Categories Service +% examples/OncDiscoveryDevices.mat - Example Usage of OncDiscovery Devices Service +% examples/OncRealTime.mat - Example Usage of OncRealTime Service +% examples/OncDeliveryDataProducts.mat - Example Usage of OncDelivery Service +% examples/OncArchive.mat - Example Usage of OncArchive Service +% +% Copyright 2024, ONC Data Team \ No newline at end of file diff --git a/onc/Onc.m b/onc/Onc.m index 939014a..02cf49d 100644 --- a/onc/Onc.m +++ b/onc/Onc.m @@ -1,7 +1,7 @@ classdef Onc < onc.OncDiscovery & onc.OncDelivery & onc.OncRealTime & onc.OncArchive - %% ONC Facilitates access to Ocean Networks Canada's data through the Oceans 2.0 API. - % For detailed information and usage examples, visit our official documentation - % at https://wiki.oceannetworks.ca/display/CLmatlab + %% ONC Facilitates access to Ocean Networks Canada's data through the Oceans 3.0 API. + % For detailed information and usage examples, run doc command or visit MATLAB's help browser + % then find Ocean Networks Canada API Client under supplemental software % % ONC Properties: % token - User token, can be obtained at: https://data.oceannetworks.ca/Profile @@ -63,20 +63,33 @@ end methods (Access = public) + %% The ONC class + % The ONC class provides a wrapper for Oceans 3.0 API requests. All the client library’s functionality is provided as methods of this class. + % Create an ONC object to access this library’s functionalities. + % Parameters: + % * token ([char]) - The ONC API token, which could be retrieved at https://data.oceannetworks.ca/Profile once logged in. + % * production (logical, optional, default = True) - + % Whether the ONC Production server URL is used for service requests. + % True: Use the production server. + % False: Use the internal ONC test server (reserved for ONC staff IP addresses). + % * showInfo (logical, optional, default = false) - + % Whether verbose script messages are displayed, such as request url and processing time information. + % True: Print all information and debug messages (intended for debugging). + % False: Only print information messages. + % * outPath ([char], optional, default = 'output') - Output path for downloaded files + % The directory will be created if it does not exist during the download. + % * timeout (int, optional, default = 60) - Number of seconds before a request to the API is canceled + % + % Returns: The Onc object created. + % + % Examples: + % onc = ONC("YOUR_TOKEN_HERE", 'showInfo', true, 'outPath', 'myOutPath'); + %% function this = Onc(token, varargin) %% Class initializer % All toolkit functionality must be invoked from an Onc object % % Onc(token, production=true, showInfo=false, outPath='output', timeout=60) - % - % * token: ([char]) User token - % - production: (logical) Send requests to the production server (otherwise use internal QA) - % - showInfo: (logical) Whether verbose debug messages are displayed - % - outPath: ([char]) Output path for downloaded files - % - timeout: (int) Number of seconds before a request to the API is canceled - % - % Returns: The Onc object created. - % parse inputs (can be named or positional) p = inputParser; addRequired(p, 'token', @ischar); @@ -128,7 +141,9 @@ this.tree = temp.tree; %These codes can then be used for input to onc.getDevices by %providing the locationCodes - + + % check if it's running the latest version. If not, throw a warning + util.checkVersion; end