https://gcore.wiki.gcube-system.org/api.php?action=feedcontributions&user=Lucio.lelii&feedformat=atomGCube System - User contributions [en]2024-03-29T13:26:58ZUser contributionsMediaWiki 1.25.1https://gcore.wiki.gcube-system.org/index.php?title=Administrator_Guide&diff=1723Administrator Guide2017-08-04T10:45:15Z<p>Lucio.lelii: /* Configuring the gHN */</p>
<hr />
<div>This Guide covers the installation, configuration, and maintenance of gCore.<br />
<br />
== Prerequisites ==<br />
<br />
The following are prerequisite for the installation of gCore:<br />
<br />
* A platform compatible [http://www.globus.org/toolkit/docs/4.0/admin/docbook/ch03.html#s-platform GT requirements].<br />
<br />
* <code>J2SE 1.6 update 4 SDK</code> or greater. [http://www.oracle.com/technetwork/java/javase/ Sun's] reference implementation is recommended, but versions from [http://www-128.ibm.com/developerworks/java/jdk/ IBM], [http://h18012.www1.hp.com/java/ HP], or [http://www.bea.com/framework.jsp?CNT=index.htm&FP=/content/products/weblogic/jrockit/ BEA] should work equally well.<br />
<br />
* <code>[http://ant.apache.org/ Ant 1.6.5+] </code> to build gCF sources or to develop services with it.<br />
<br />
* an SVN client to install gCore from the SVN repository.<br />
<br />
* <code>[http://www.gnu.org/software/tar/tar.html GNU tar]</code> to install gCore from archived distributions.<br />
<br />
* <code>[http://www.courtesan.com/sudo/ sudo]</code> privileges on the shell.<br />
<br />
The following are pre-requisites for the operation of gHN in any infrastructure:<br />
<br />
* A static IP address and preferably a DNS name.<br />
<br />
The following are pre-requisites for the operation of gHN in a secure infrastructure:<br />
<br />
* A [http://www.ntp.org/ ntp server] to synchronise the machine's clock for correct credential validation. <br />
<br />
* A host certificate and private key owned by the user that runs the container and stored in an arbitrary position on the machine: the paths must be set in the ''global security descriptor'' file, as described in [https://gcube.wiki.gcube-system.org/gcube/index.php/GHN_Security_Configuration#Security_Configuration_provided GHN security configuration] section. In the most of cases the certificate and the key are stored respectively in:<br />
<br />
<code>/etc/grid-security/hostpubliccert.pem</code> (please check that the certificate file has -rw-r--r-- permissions)<br />
<code>/etc/grid-security/hostprivatekey.pem</code> (please check that the private key file has -r-------- permissions).<br />
<br />
* The public keys of the certification authorities to be accepted by the GHN,owned by the user that runs the container and stored in:<br />
<br />
<code>/etc/grid-security/certificates</code> (the permissions are -rw-r--r--)<br />
<br />
for further information, please refer to [https://gcube.wiki.gcube-system.org/gcube/index.php/GHN_Security_Configuration gCube security configuration] section.<br />
<br />
== Installation ==<br />
<br />
Once [[Status_&_Downloads|downloaded]], gCore can be installed in a directory of choice (the ''gCore location''). In either case, proceed to the installation as a a non-privileged user with read and write permissions on the gCore location. Due to some technical constraints, the current version of gCore requires that different installations must run under different users, i.e. the same user cannot configure and execute more than one container. <br />
<br />
The structure of the installation is the following:<br />
<br />
<pre><br />
|-bin<br />
|<br />
|-config<br />
|<br />
|-endorsed<br />
|<br />
|-etc<br />
|<br />
|-lib<br />
|<br />
|-libexec<br />
|<br />
|-logs<br />
|<br />
|-share<br />
</pre><br />
<br />
Some folders are of immediate interest to administrators and developers alike:<br />
<br />
{| class="wikitable" border="1"<br />
|-<br />
| '''<code>bin</code>'''<br />
| executables.<br />
|-<br />
| '''<code>config</code>'''<br />
| gHN configuration files.<br />
|-<br />
| '''<code>etc</code>'''<br />
| configuration files of container's and deployed service.<br />
|-<br />
| '''<code>lib</code>'''<br />
| standard and deployed service libraries.<br />
|-<br />
| '''<code>logs</code>'''<br />
| Log files for gHN, Local Services, and legacy technologies.<br />
|-<br />
| '''<code>share</code>'''<br />
| build tools, standard and deployed service interfaces and schemas.<br />
|}<br />
<br />
== Third-party software ==<br />
gCore ships a number of third party products. The source material is copyright of the original publishers and software are governed by the terms and conditions of the third-party software.<br />
<br />
Here it is a complete list grouped by provider.<br />
<br />
'''Apache Software Foundation (AFS) ANT'''<br />
* ant-launcher 1.6.5<br />
* ant 1.6.5<br />
* antlr 2.7.6<br />
<br />
'''ASF AXIS'''<br />
* addressing 1.0<br />
* axis 1.2RC (globus patched)<br />
* saaj 1.2RC<br />
* jaxrpc 1.2RC<br />
* axis-url 1.2.6<br />
* wsdl4j 1.2RC <br />
<br />
'''ASF XML'''<br />
* resolver 1.1.1<br />
* xercesImpl 2.6.2<br />
* xml-apis 2.6.2<br />
* xmlsec 1.2.1<br />
* xalan 2.6<br />
<br />
'''ASF COMMONS'''<br />
* commons-beanutils 1.6.1<br />
* commons-cli 2.0<br />
* commons-collections 3.0 <br />
* commons-digester 1.2<br />
* commons-discovery 0.2dev<br />
* commons-io 1.2<br />
* commons-lang 2.4<br />
* commons-logging 1.1.1<br />
<br />
'''Tomcat 4.1 '''<br />
* naming-java 4.1<br />
* naming-resources 4.1<br />
* naming-factory 4.1 <br />
* naming-common 4.1<br />
<br />
'''GLOBUS 4.0.x'''<br />
* cog-axis<br />
* cog-jglobus<br />
* cog-tomcat<br />
* cog-url<br />
* puretls 0.9b4<br />
* cryptix-asn1 ?<br />
* cryptix.jar ?<br />
* cryptix32 3.2.0<br />
* bootstrap ?,<br />
* globus_usage_core<br />
* globus_usage_packets_common<br />
* globus_wsrf_mds_aggregator<br />
* globus_wsrf_mds_aggregator_stubs <br />
* globus_wsrf_servicegroup<br />
* globus_wsrf_servicegroup_stubs, <br />
* wsrf_common<br />
* wsrf_core<br />
* wsrf_mds_index_stubs<br />
* wsrf_mds_usefulrp<br />
* wsrf_test<br />
* wsrf_tools<br />
* wsrf_mds_usefulrp_schema_stubs<br />
* wsrf_provider_jce<br />
* wsrf_core_stubs<br />
* wsrf_mds_index<br />
<br />
'''gLite'''<br />
* glite-security-util-java 1.3.4<br />
<br />
'''MISC'''<br />
* cglib 2.2<br />
* objenesis 1.1<br />
* bcprov-jdk14 1.2.2<br />
* jce-jdk13 1.2.5<br />
* concurrent ?<br />
* SUN servlet.jar 2.3/1.2(JSP)<br />
* opensaml 1.0.1 (globus patched)<br />
* kxml2 2.3.0 <br />
* log4j 1.2.15 <br />
* jgss ?<br />
* junit 3.8.1<br />
* wss4j ?<br />
* SUN jsr173_api ?<br />
* BEA commonj 1.1<br />
* Jaxen XPath library - jaxen-1.1-beta-9.jar<br />
<br />
== Configuration ==<br />
<br />
Configuring the installation can be roughly distributed across the following steps: configuring the environment, the container, the gHN associated with a running instance of the container, and the operation of the gHN in a secure infrastructure.<br />
<br />
=== Configuring the Environment ===<br />
<br />
:*Define an environment variable '''<code>GLOBUS_LOCATION</code>''' and point it to the gCore location. Assuming a bash shell:<br />
<br />
:<pre>export GLOBUS_LOCATION=absolute path to your gCore location</pre><br />
<br />
:* (optional) Add ''<code>$GLOBUS_LOCATION/bin</code>'' to the value of your '''<code>PATH</code>''' environment variable.:<br />
<br />
:<pre>export PATH=$PATH:$GLOBUS_LOCATION/bin</pre><br />
<br />
:* (optional) If building gCF-compliant services, define an environment variable '''<code>BUILD_LOCATION</code>''' and set it to the location from which <code>ant</code> will be invoked and where temporary build structures and artefacts will be located:<br />
<br />
:<pre>export BUILD_LOCATION=absolute path to your build location</pre><br />
<br />
=== Configuring the Container ===<br />
<br />
Specify the hostname of your machine as the value of ''logicalHost'' parameter in the container's configuration file ''$GLOBUS_LOCATION/etc/globus_wsrf_core/server-config.wsdd'':<br />
<br />
<pre><parameter name="logicalHost" value="..yourhostname..."/></pre><br />
<br />
In the default configuration, the container typically allocates '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be increased by setting new parameters in the <code>$GCORE_START_OPTIONS</code> variable, either by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> or by adding it to the execution environment. If one wants to decrease the memory used, it is needed to edit the script, since, due to the Java Virtual Machine behavior, in case of duplicated setting, the higher setting is considered.<br />
<br />
Moreover, any setting reported in the <code>$GCORE_START_OPTIONS</code> variable is passed to the container process and evaluated by the JVM.<br />
<br />
=== Configuring the gHN ===<br />
<br />
The configuration of the gHN that relates to its operation within the infrastructure and can be found in <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code>. The file <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code> ''can'' be used to dedicate a separate configuration to a gHN that operates in [[Contexts#The_gHN_Context|client mode]].<br />
<br />
The following gHN properties are available for configuration:<br />
<br />
<br />
{| class="wikitable" border="1"<br />
|-<br />
| '''<code>securityenabled</code>'''<br />
| <code>true</code> if the gHN can operate in a secure infrastructure, <code>false</code> otherwise.<br />
|-<br />
| '''<code>accountingenabled</code>'''<br />
| <code>true</code> if the gHN must account using the gcube accounting system on every call received, <code>false</code> otherwise.<br />
|-<br />
| '''<code>mode</code>'''<br />
| either '''<code>CONNECTED</code>''' or '''<code>STANDALONE</code>''' depending on whether the gHN does or does not publish information in the infrastructure. <br />
|-<br />
| '''<code>infrastructure</code>'''<br />
| the name of the infrastructure in which the gHN operates. (e.g. <code>gcube</code>, <code>d4science</code>,...).<br />
|-<br />
| '''<code>startScopes</code>'''<br />
| a comma-separated list of VOs that the gHN joins.<br />
|-<br />
| '''<code>allowedScopes</code>'''<br />
| a comma-separated list of VOs that the gHN will potentially join (upon VO Manager decision).<br />
|-<br />
| '''<code>labels</code>'''<br />
| the name of the file that includes custom labels to characterize the gHN. These are added to those automatically derived by gCore and published in the gHN profile. The file name must be relative to the <code>$GLOBUS_LOCATION/config</code> directory.<br />
|-<br />
| '''<code>GHNtype</code>'''<br />
| either '''<code>DYNAMIC</code>''' or '''<code>STATIC</code>''' depending on whether the gHN can or cannot be used as a target for dynamic deployment operations.<br />
|-<br />
| '''<code>coordinates</code>'''<br />
| a pair of comma-separated values for the latitude and longitude of the gHN. Coordinates for some popular locations are available [[gHN Coordinates|here]].<br />
|-<br />
| '''<code>country</code>'''<br />
| the two-character [http://www.iso.org/iso/english_country_names_and_code_elements ISO code] of the Country where the gHN is located. <br />
|-<br />
| '''<code>location</code>'''<br />
| the name of the location.<br />
|-<br />
| '''<code>publishedHost</code>'''<br />
| the hostname to declare in the GHN and Running Instance profiles, if different from the actual one<br />
|-<br />
| '''<code>publishedPort</code>'''<br />
| the port to declare in the GHN and Running Instance profiles, if different from the actual one<br />
|-<br />
| '''<code>updateInterval</code>'''<br />
| how often the gHN must has to refresh its profile on the IS (in seconds).<br />
|-<br />
| '''<code>portRange</code>''' [optional]<br />
| a dash-separated pair of numbers that identify a range of free ports, if any.<br />
|-<br />
| '''<code>testInterval</code>''' [optional]<br />
| how often the monitoring Probes have to perform local test on the gHN<br />
|}<br />
<br />
For example, the configuration required to join the gHN to the <code>/gcube/devsec</code> and <code>/gcube/testing</code> VOs is the following:<br />
<br />
<pre><br />
infrastructure = gcube <br />
startScopes = devsec,testing<br />
</pre><br />
<br />
For an in-depth coverage of scope and scope-related parameters (infrastructure and startScopes) see the [[Scope_Management|Developer Guide]].<br />
<br />
=== Configuring Logging ===<br />
<br />
A running gCore container will produce extensive logs in accordance with the [http://logging.apache.org/log4j/ log4j] configuration directives container in <code>$GLOBUS_LOCATION/container-log4j.properties</code>. By default, the container logs in a file called <code>$GLOBUS_LOCATION/logs/container.fulllog</code> with a <code>TRACE</code> level for all the gCF components, and in <code>$GLOBUS_LOCATION/logs/container.log</code> with a <code>INFO</code> level for all the gCF components. Local Services have also dedicated file loggers.<br />
<br />
==== Configuring Access Logs purging====<br />
<br />
Starting from GHN v 3.7.0, the GHN distribution contains a mechanism to clean access log files from the system ( that in some cases can occupy a considerable amount of space).<br />
<br />
The script ''gcore-clean-accesslogs'' can be used to remove accesslogs older than 7 days ( configurable) and it can also be installed as cronjob via the ''gcore-clean-accesslogs-cron''. Both files are located under the $GLOBUS_LOCATION/bin folder of the GHN.<br />
<br />
In case of older versions of GHN distributions the files can be downloaded from:<br />
<br />
* http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/distributions/ghn-distribution-bundle/gCore/bin/gcore-clean-accesslogs<br />
* http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/distributions/ghn-distribution-bundle/gCore/bin/gcore-clean-accesslogs-cron<br />
<br />
and installed under the $GLOBUS_LOCATION/bin folder.<br />
<br />
PLEASE NOTE : the scripts assume that the GLOBUS_LOCATION var is set inside the $HOME/.profile or $HOME/.bashrc<br />
<br />
===Configuring container security===<br />
<br />
//OUTDATED SECTION<br />
Detailed information about secure container configuration is provided in [https://gcube.wiki.gcube-system.org/gcube/index.php/GHN_Security_Configuration gCube security configuration] section.<br />
<br />
Detailed information about not default settings (for example, interoperability with secure external infrastructure or with a VOMS server, is availabled in [https://gcube.wiki.gcube-system.org/gcube/index.php/Security_Library#Extension_Security_Libraries Security Libraries] section of gCube wiki.<br />
//END OF OUTDATED SECTION<br />
<br />
=== Supporting resource encryption/decryption ===<br />
<br />
If the gHN is foreseen to manage gCube encrypted resources, the [http://goo.gl/qTZO0j "AES symmetric key"] has to be downloaded and stored in the $GLOBUS_LOCATION/config folder.<br />
Alternatively a new compatible symmetric key could be generated by typing on linux shell the following: <br />
<br />
<pre> openssl rand -out symm.key 16 </pre><br />
<br />
== Verify the Installation ==<br />
<br />
To verify the installation, firstly start the container with the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> in a not secure infrastructure, or <code>$GLOBUS_LOCATION/bin/gcore-start-secure-container</code> in a secure infrastructure. So, assuming <code>PATH</code> is set as recommended above:<br />
<br />
<pre>gcore-start-container</pre><br />
or<br />
<pre>gcore-start-secure-container</pre><br />
<br />
will suffice. Any instance of the container which is already running should be automatically ''kill''-ed.<br />
By default, the commands above start the container on the port <code>8080</code> in a not secure infrastructure, <code>8443</code> in a secure infrastructure. To switch on another port, use the <code>-p <port></code> option.<br />
<br />
Then, two steps can be performed to verify that the container is locally working fine:<br />
<br />
# the new instance should log the list of deployed services in <code>$GLOBUS_LOCATION/nohup.out <code> and detailed information about the startup of local services in <code>$GLOBUS_LOCATION/logs/container.log</code>. Lack of visible errors in both files indicates a successful gCore installation and startup.<br />
# stopping the container, which is an action that contacts the container itself. For this, use the appropriate stop command, according to your configuration: <br />
<pre>gcore-stop-container</pre><br />
or<br />
<pre>gcore-stop-secure-container</pre><br />
<br />
Finally, for a full exploitation of the container (e.g. remote management and deployment, and having your services contacted), the host and port must be public and reachable from outside.<br />
<br />
== Troubleshooting ==<br />
<br />
=== gHN with a high number of invocations ===<br />
<br />
If a gHN hosts a service instance subjects to a high number of invocations, it might happen that the gContainer stops to serve callers' requests. This is due to mistaken usage of the "id" command of the underlying technology. Soon, the process will fall into a "too many files open" state and it basically does nothing from that moment on.<br />
<br />
When such a condition is predictable, we suggest to create a temporary folder for the system commands, remove the "id" command from there and use that folder in the PATH instead the "official" one.<br />
<br />
The complete workaround is the following:<br />
<br />
* create a folder where to collect the system commands:<br />
<br />
<pre><br />
mkdir fakebin<br />
cd fakebin<br />
find /usr/bin -type f -exec ln {} \;<br />
find /usr/bin -type l -exec cp -a {} . \;<br />
rm id<br />
</pre><br />
<br />
* remove the /usr/bin folder from the PATH <br />
<br />
* add the new fakebin folder to the PATH<br />
<br />
Of course, this could have impact on the other processes, therefore the new patched environment must be used only for the gContainer process.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1343Migration Guidelines from 0.4.4 to 0.52009-05-05T11:37:15Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: The <code>ISNotifier</code> interface now supports a new method to check if a Topic registration is finished successful, the signatures of the other method are changed. See the Primer for examples [[Advanced_Topics#ISNotifier_interface|on usage]].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1342Migration Guidelines from 0.4.4 to 0.52009-05-05T11:33:12Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: The <code>ISNotifier</code> interface now supports a new method to check if a Topic registration is finished successful, the signatures of the other method are changed. See the Primer for examples [[/Advanced_Topics#ISNotifier_interface|on usage]].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1341Migration Guidelines from 0.4.4 to 0.52009-05-05T11:30:46Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and require a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures require a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: ['''Please summarise and point to primer section similarly to entry above'''].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1340Migration Guidelines from 0.4.4 to 0.52009-05-05T11:29:41Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and requires a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and requires a GCUBESecurityManager instead of ServiceContext parameter. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures requires a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures requires a GCUBESecurityManager instead of ServiceContext parameter.<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: ['''Please summarise and point to primer section similarly to entry above'''].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1339Migration Guidelines from 0.4.4 to 0.52009-05-05T10:55:16Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and the ServiceContext parameter is now a GCUBESecurityManager. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:: The signatures have lost the following parameters conusmerEPR because they proved superfluous and the ServiceContext parameter is now a GCUBESecurityManager. <br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: ['''Please summarise and point to primer section similarly to entry above'''].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1338Migration Guidelines from 0.4.4 to 0.52009-05-05T10:49:51Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes'''<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes'''<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes'''<br />
:* '''the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes'''<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: ['''Please summarise and point to primer section similarly to entry above'''].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Migration_Guidelines_from_0.4.4_to_0.5&diff=1337Migration Guidelines from 0.4.4 to 0.52009-05-05T10:48:35Z<p>Lucio.lelii: /* Changes Related to Services */</p>
<hr />
<div>gCore <code>0.5.0RC</code> requires or supports the following changes to practices and implementations that are compliant with gCore 0.4.4:<br />
<br />
==== Changes Related to the gHN ====<br />
<br />
:* ''package change in <code>ResultSet</code> components''<br />
::The inclusion of the <code>ResultSet</code> service and related components in gCore has coincided with a refactorisation of their package structure. In particular, fully qualified names that begun with <code>org.gcube.searchservice</code> begin now with <code>org.gcube.common.searchservice</code>.<br />
<br />
:* ''new log files and log file location.''<br />
:: All gCore logs are now located in <code>$GLOBUS_LOCATION/logs</code>, while <code>nohup.out</code> remains in <code>$GLOBUS_LOCATION</code> (now regardless of where the <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> is run from). The gHN's logs remains the same (<code>container.fulllog</code>, <code>container.log</code>), but the local services have dedicated log files (<code>ghnmanager.log</code>,<code>deployer.log</code>, <code>delegation.log</code>, <code>rs.log</code>). Globus logs are now collected in a separate log file <code>globus.log</code> and do not propagate to the contatainer's log files (default log level for globus is <code>WARN</code>). Developers are recommended to configure service-specific logs during development. For this purpose, the configuration for local services in <code>$GLOBUS_LOCATION/container-log4j.properties</code> can be used as templates.<br />
<br />
:* ''new lower bound on memory requirement for gHNs.''<br />
:: The gHN now requires the allocation of '''1GB''' of heap space to the JVM in which it runs. This is a production-level requirement and can be disabled or corrected during development by editing the script <code>$GLOBUS_LOCATION/bin/gcore-start-container</code> (<code>START_OPTIONS</code> variable).<br />
<br />
:* ''new gHN configuration file for offline use.''<br />
:: gCore ships with a clone of <code>$GLOBUS_LOCATION/config/GHNConfig.xml</code> called <code>$GLOBUS_LOCATION/config/GHNConfig.client.xml</code>. The latter can diverge arbitrarily from the former so as to decouple offline and online use of the gHN.<br />
<br />
:* ''(optional) configuration of free port range for the gHN.''<br />
::Administrators and developers can now specify a <code>portRange</code> environment in <code>$GLOBUS_LOCATION/configs/GHNConfig.xml</code>' (or <code>$GLOBUS_LOCATION/configs/GHNConfig.client.xml</code> if useful). The value of the environment can be specified as in the following example:<br />
<br />
:<pre><environment name="portRange" value="60000-61000" type="java.lang.String" /></pre><br />
<br />
:: Do note the following:<br />
::* The configuration does not imply that the ports are actually 'open', only that they can be bound.<br />
::* The gHN management interface (see below) depends on the existence of this configuration.<br />
::* The first free port in this range can be obtained by invoking the method <code>getFreePort()</code> om the <code>GHNContext</code>. See the Javadoc documentation for details of the signature.<br />
<br />
:* ''(optional) use of the JMX management interface.''<br />
:: The gHN now binds a JMX managemenet interface to the port that it finds free in the configured range (see above). The bound port is shown in the gHN logs:<br />
<br />
:<pre>...GHNContext: INITIALISED MANAGEMENT INTERFACE AT service:jmx:rmi:///jndi/rmi://localhost:60000</pre><br />
<br />
:: The interface can then be used with <code>jconsole</code>, a graphical JMX client that ships with the JDK:<br />
<br />
:<pre>jconsole localhost:60000</pre><br />
<br />
::gHN-specific and RI-specific information and operations can be found in the <code>MBeans</code> tabbed pane under <code>org.gcube</code>. In the same tabbed pane, logger and appender information and operations can be found under <code>log4j</code>.<br />
<br />
==== Changes Related to Services ====<br />
<br />
:* '''<code>org.gcube.common.core.resources.GCUBETransformationProgram</code> and <code>org.gcube.common.core.resources.GCUBEVRE</code> are no longer available.'''<br />
::These types were not in use as the corresponding resources are modelled with <code>org.gcube.common.core.resources.GCUBEGenericResource</code>.<br />
<br />
:* '''the methods <code>org.gcube.common.core.state.GCUBEStatefulResource.isRemoved()</code> and <code>org.gcube.common.core.state.GCUBEStatefulResource.remove()</code> are no longer available.'''<br />
::<code>isRemoved()</code> was intended primarily for internal usage and has been made redundant by the [[#locking|new locking mechanism]], which should now be used by developers. <code>remove()</code> was thread-unsafe as all removal operations should pass for the method <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.state.GCUBEStatefulResource.getPersistenceDelegate()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Exposing persistence delegates is no longer necessary and in fact dangerous. Resource load must be handled transparently by the home associated with the resource, and resource storage can be triggered by invoking directly the method <code>org.gcube.common.core.state.GCUBEStatefulResource.store()</code>.<br />
<br />
:* '''the method <code>org.gcube.common.core.utils.events.GCUBEProducer.registerTopics()</code> was already <code>deprecated</code> and is now no longer available.'''<br />
::The registration of topics is now performed implicitly at the notification of the first event in a given topic.<br />
<br />
:* '''the method <code>org.gcube.common.core.context.GCUBEServiceContext.getConfigFile()</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
:: The method is replaced by <code>org.gcube.common.core.context.GCUBEServiceContext.getFile()</code>. See [[#filemanagement|below]] for furter information.<br />
:* the method <code>org.gcube.common.core.informationsystem.notifier.registerToISNotification</code> have new, non retro-compatible changes<br />
:* the method <code>org.gcube.common.core.informationsystem.notifier.unregisterFromISNotification</code> have new, non retro-compatible changes<br />
:* the method <code>org.gcube.common.core.informationsystem.notifier.registerISNotification</code> have new, non retro-compatible changes<br />
:* the method <code>org.gcube.common.core.informationsystem.notifier.unregisterISNotification</code> have new, non retro-compatible changes<br />
:* '''<code>org.gcube.common.core.porttypes.GCUBEStartupPortType</code> is now <code>deprecated</code> and will be removed in the next minor/major release.'''<br />
::Derive now ''all'' port-type implementations from <code>org.gcube.common.core.porttypes.GCUBEPortType</code>, regardless of the value set in their deployment descriptors for <code>loadOnStartup</code>. Do note that:<br />
::* The requirement that <code>loadOnStartup</code> be set to <code>true</code> for at least one port-type implementation does remain.<br />
::* The requirements to derive <code>GCUBEPortType</code> are the same requirements to derive <code>GCUBEStartupPortType</code> (i.e. implement the method <code>getServiceContext()</code>).<br />
:: Note also that <code>GCUBEStartupPortType</code> is recast as a subclass of <code>GCUBEPortType</code> for this release only.<br />
:: See also the Primer for more information [[The_Development_Cycle#A_Simple_Implementation|on this requirement]].<br />
<br />
:* ''New port-type and home callbacks on RI lifetime.''<br />
:: <code>org.gcube.common.core.porttypes.GCUBEPortType</code> defines callbacks for all the states of RI lifetime: <code>onInitialisation()</code>, <code>onInitialisation()</code>onReady()</code, <code>onFailure()</code>, <code>onUpdate()</code>,<code>onStateChange()</code>. The same callbacks are now also defined for <code>org.gcube.common.core.state.GCUBEResourceHome.remove()</code>. See the Developer's Guide for specific information on the [[Contexts#Lifetime_Management_2|lifetime of the RI]].<br />
<br />
<div id="filemanagement"></div><br />
:* ''New file management methods on service contexts.''<br />
::Service contexts offer two methods to write and read files from the file system: <code>getFile()</code> and <code>getPersistentFile()</code>. The usage model and difference between the two methods are described in detail in the Developer's Guide, first [[Contexts#Common_Facilities|here]] and then [[Contexts#Configuration_and_File_Management|here]] . Do notice that, changes to persistent files must be explicitly notified to the persistence manager (see below), if one is configured for the service.<br />
<br />
:* ''(Optional) configuration of remote backup/recovery.''<br />
:: Services that wish to take advantage of the new facility for remote backup and recovery can do so by adding the a <code>persistenceManagerProfile</code> resource to their <code>deploy-jndi-xml</code>, as follows:<br />
<br />
<pre><br />
<resource name="persistenceManagerProfile" type="org.gcube.common.core.persistence.GCUBERIPersistenceManagerProfile"><br />
<resourceParams> <br />
<parameter><name>factory</name><value>org.globus.wsrf.jndi.BeanFactory</value></parameter> <br />
<parameter><name>className</name><value>org.gcube.common.smspersistence.GCUBESMSPersistenceManager</value><br />
</parameter><parameter><name>monitoringInterval</name><value>...value in seconds...</value></parameter> <br />
</resourceParams><br />
</resource><br />
</pre><br />
<br />
:: Do note the following:<br />
::* <code>className</code> specifies the class of the only SMS-based persistence manager that ships with gCore<br />
::* <code>monitoringInterval</code> measures ''in seconds'' how often the persistent manager will backup the RI state, if and only if this has changed since the last backup.<br />
::* changes to persisted WS-Resources are automatically detected by the persistence manager. Changes to other files below the storage root of the service must be explicitly flagged by invoking the method <code>org.gcube.common.core.context.GCUBEServiceContext.notifyStateChange()</code>. <br />
:: See also the release notes for an [[Release_Notes|overview of remote persistence]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.client.ISClient</code>'' interface.''<br />
:: The <code>ISClient</code> interface now supports query by reference. See the Primer for examples [[/Advanced_Topics#ISClient_interface|on usage]].<br />
<br />
:* ''New ''<code>org.gcube.common.core.informationsystem.notifier.ISNotifier</code>'' interface.''<br />
:: ['''Please summarise and point to primer section similarly to entry above'''].<br />
<br />
:* ''New persistence modes for'' <code>org.gcube.common.core.state.GCUBEResourceHome</code>.<br />
:: Resource homes can now be configured to support additional modes of persistence. See the Primer for an explanation of the [[Adding_State#Persistence_Modes|available modes and configuration details]].<br />
<br />
<div id="locking"></div><br />
:* ''New locking mechanism for resources.''<br />
:: <code>org.gcube.common.core.state.GCUBEStatefulResource</code> now defines a method <code>getLock()</code> that returns a new <code>org.gcube.common.core.state.GCUBEReadWriteLock</code> that can be used by cooperating threads (including gCF's of course) to synchronise their access to the resource. <code>GCUBEReadWriteLock</code> is an extension of Java's [http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html <code>ReadWriteLock</code>] which supports ''pre-emptive'' write locks (if one thread succeeds the others waiting for the lock are interrupted). This should be of limited interest to the vast majority of developers as the pre-emptive behaviour is used transparently by gCF on removal operations. Do use <code>GCUBEReadWriteLock</code> as a standard read-write lock otherwise.<br />
<br />
:* ''New interface for sychronous consumers.''<br />
::The tagging interface <code>org.gcube.common.core.utils.events.GCUBESynchronousConsumer</code> is now available for consumers that wish producers to block in their delivery of events.</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1336Advanced Topics2009-05-05T10:19:55Z<p>Lucio.lelii: /* ISClient interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope) throws ISMalformedQueryException,ISUnsupportedQueryException,ISException; <br />
</pre><br />
<br />
<pre><br />
public <RESULT> ISInputStream<RESULT> executeByRef(ISQuery<RESULT> q, GCUBEScope s) throws ISMalformedQueryException,ISUnsupportedQueryException,ISException;<br />
</pre><br />
<br />
The two execute methods take as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
<br />
The return type in the first case is a List object specified as Type parameter in the related ISquery object, in the second case is a ISInputStream that implements the java.lang.iterable interface.<br />
<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications,<br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Checks if the producer registration is completed or not <br />
* <br />
* @param the topic to check<br />
* @param EnpointReferenceType of the producer<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification<br />
* @return true if the registration is completed, false otherwise<br />
*/<br />
public boolean isTopicRegistered(QName Topic, EndpointReferenceType producerEpr, GCUBESecurityManager manager, GCUBEScope scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
<br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
protected static final String RP_NAME = "Name"; <br />
protected static String[] TopicNames={RP_NAME};<br />
<br />
@Override<br />
public String[] getTopicNames(){<br />
return TopicNames;<br />
} <br />
<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1335Advanced Topics2009-05-05T10:19:30Z<p>Lucio.lelii: /* ISClient interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope) throws ISMalformedQueryException,ISUnsupportedQueryException,ISException; <br />
</pre><br />
<br />
<pre><br />
public <RESULT> ISInputStream<RESULT> executeByRef(ISQuery<RESULT> q, GCUBEScope s) throws ISMalformedQueryException,ISUnsupportedQueryException,ISException;<br />
</pre><br />
<br />
The two execute methods take as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
<br />
The return type in the first case is a List object specified as Type parameter in the related ISquery object, in the second case is a ISInputStream that implement the java.lang.iterable interface.<br />
<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications,<br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Checks if the producer registration is completed or not <br />
* <br />
* @param the topic to check<br />
* @param EnpointReferenceType of the producer<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification<br />
* @return true if the registration is completed, false otherwise<br />
*/<br />
public boolean isTopicRegistered(QName Topic, EndpointReferenceType producerEpr, GCUBESecurityManager manager, GCUBEScope scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
<br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
protected static final String RP_NAME = "Name"; <br />
protected static String[] TopicNames={RP_NAME};<br />
<br />
@Override<br />
public String[] getTopicNames(){<br />
return TopicNames;<br />
} <br />
<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1321Advanced Topics2009-05-04T17:28:18Z<p>Lucio.lelii: /* ISNotifier interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications,<br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Checks if the producer registration is completed or not <br />
* <br />
* @param the topic to check<br />
* @param EnpointReferenceType of the producer<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification<br />
* @return true if the registration is completed, false otherwise<br />
*/<br />
public boolean isTopicRegistered(QName Topic, EndpointReferenceType producerEpr, GCUBESecurityManager manager, GCUBEScope scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
<br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
protected static final String RP_NAME = "Name"; <br />
protected static String[] TopicNames={RP_NAME};<br />
<br />
@Override<br />
public String[] getTopicNames(){<br />
return TopicNames;<br />
} <br />
<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1319Advanced Topics2009-05-04T17:06:34Z<p>Lucio.lelii: /* ISNotifier interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications,<br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Checks if the producer registration is completed or not <br />
* <br />
* @param id the registration ID<br />
* @param security manager the {@link GCUBESecurityManager} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification<br />
* @return true if the registration is completed, false otherwise<br />
*/<br />
public boolean isCompleted(QName Topic, EndpointReferenceType producerEpr, GCUBESecurityManager manager, GCUBEScope scope) throws ISNotifierException;<br />
<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
<br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
protected static final String RP_NAME = "Name"; <br />
protected static String[] TopicNames={RP_NAME};<br />
<br />
@Override<br />
public String[] getTopicNames(){<br />
return TopicNames;<br />
} <br />
<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1248Advanced Topics2009-04-27T13:29:46Z<p>Lucio.lelii: /* Resource Properties as Topics */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
<br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
protected static final String RP_NAME = "Name"; <br />
protected static String[] TopicNames={RP_NAME};<br />
<br />
@Override<br />
public String[] getTopicNames(){<br />
return TopicNames;<br />
} <br />
<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1247Advanced Topics2009-04-27T13:25:14Z<p>Lucio.lelii: /* ISNotifier interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
@Override<br />
protected String[] getTopicNames(){<br />
return new String[] {"DeployedPackages"};<br />
}<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=1246Advanced Topics2009-04-27T13:23:54Z<p>Lucio.lelii: /* ISNotifier interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Framework has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can exploit the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The GCUBEResource to register<br />
* @param scope the scope in which the resource is going to be registered<br />
* @param the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the GCUBEResource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the scope from which the resource is going to be removed<br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource the new GCUBEResource to update <br />
* @param manager the GCUBESecurityManager for contacting the IS<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS (the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
As noticed, the ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
=== ISNotifier interface ===<br />
Topics publishers can use the ISNotifier interface, to let their Topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Registers the consumer to the given list of topics<br />
* <br />
* @param notifications the list of IS Notification to register to<br />
* @param consumer the {@link BaseNotificationConsumer} to callback whenever a notification is received<br />
* @param context the {@link GCUBEServiceContext} of the consumer <br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public <T extends BaseNotificationConsumer> void registerToISNotification(List<QName> notifications, T consumer, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
<br />
/**<br />
* Unregisters the consumer from the given list of topics <br />
* <br />
* @param notifications the list of IS Notifications from which to unregister the {@link EndpointReferenceType}<br />
* @param context the {@link GCUBEServiceContext} of the consumer<br />
* @param scope the {@link GCUBEScope}s in which to register the consumer, replacing the one included in the context<br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterFromISNotification(List<QName> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
<br />
/**<br />
* Registers a list of topics as IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer <br />
* @param notifications the list of IS Notifications to register<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to register the IS notification, it is used instead of the one included in the context<br />
* @throws ISNotifierException if the registration fails<br />
*/<br />
public void registerISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, <br />
GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException ;<br />
<br />
/**<br />
* Unregisters a list of new topics as source of IS Notifications<br />
* <br />
* @param producerEPR the {@link GCUBEServiceContext} of the producer<br />
* @param notifications the list of IS Notification to unregister<br />
* @param context the {@link GCUBEServiceContext} of the producer<br />
* @param scope the {@link GCUBEScope}s in which to unregister the IS notification, it is used instead of the one included in the context<br />
* <br />
* @throws ISNotifierException if the unregistration fails<br />
*/<br />
public void unregisterISNotification (EndpointReferenceType producerEPR, List<? extends Topic> notifications, GCUBESecurityManager manager, GCUBEScope ... scope) throws ISNotifierException;<br />
</pre><br />
<br />
==== Resource Properties as Topics ====<br />
In order to publish one or more Resource Properties as Topics in the IS, one needs to override in the ws-resoure class the getTopics() method in order to provide the names of the RP that he/she wants to publish as Topics<br />
<br />
Example:<br />
<pre><br />
<br />
public class DeployerResource extends GCUBEWSResource {<br />
<br />
@Override<br />
protected String[] getTopicNames(){<br />
return new String[] {"DeployedPackages"};<br />
}<br />
</pre><br />
<br />
And, that's all. GCF automatically publishes on behalf of the resource the Topics, as it does with the RP<br />
<br />
==== Generic Topics ====<br />
In order to publish a Topic not directly bound to a Resource Property, the following steps must be followed.<br />
<br />
1) Define your own Topic in your WSResource<br />
<br />
Example:<br />
<pre><br />
public static final String NS = "http://gcube-system.org/namespaces/vremanagement/deployer";<br />
<br />
private SimpleTopic deployedPackagesT = new SimpleTopic(new QName(NS, “TopicName"));<br />
</pre><br />
<br />
<br />
… and the Topic notification message in the WSDL<br />
<br />
<pre><br />
<xsd:element name=" DeployedPackagesNotificationMessage" type="tns:DeployedPackagesNotificationMessageType"/><br />
</pre><br />
<br />
2) Retrieve the ISNotifier implementation<br />
<br />
Example:<br />
<pre><br />
ISNotifier notifier = GHNContext.getImplementation(ISNotifier.class);<br />
</pre><br />
<br />
3) Register the Topic<br />
<br />
Example:<br />
<pre><br />
List <SimpleTopic> list = new ArrayList< SimpleTopic >();<br />
list.add(deployedPackagesT );<br />
notifier.registerISNotification(this.getEPR(), list, this.getServiceContext());<br />
</pre><br />
<br />
4) Send the notification whenever it is needed, according to the notification message defined in the WSDL<br />
<br />
Example:<br />
<pre><br />
DeployedPackagesNotificationMessageType message = new DeployedPackagesNotificationMessage ();<br />
message.setX(…);<br />
message.setY(…)<br />
<br />
deployedPackagesT.notify(message);<br />
</pre><br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Managing_State&diff=913Managing State2008-10-15T15:09:57Z<p>Lucio.lelii: /* Publication Profile */</p>
<hr />
<div>== How to publish the state ==<br />
=== GCUBEProvider ===<br />
Import GCUBEProvider WSDL inside the Stateful WSDL:<br />
<pre><br />
<definitions name="Stateful" targetNamespace="http://acme.org/sample" ....<br />
xmlns:wsdlpp="http://www.globus.org/namespaces/2004/10/WSDLPreprocessor"<br />
xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"<br />
xmlns:provider="http://gcube-system.org/namespaces/common/core/porttypes/GCUBEProvider" /><br />
<br />
<import namespace=http://gcube-system.org/namespaces/common/core/porttypes/GCUBEProvider <br />
location="../gcube/common/core/providers/GCUBEProvider.wsdl"/><br />
<br />
...<br />
<br />
</definition><br />
</pre><br />
<br />
Include the GCUBEProvider in the list of providers on service WSDD:<br />
<pre> <br />
<parameter name="providers" value="GCUBEProvider"/><br />
</pre><br />
<br />
=== WS-Resource Property document ===<br />
Declare the WS-Resource Property document in the Stateful WSDL:<br />
<pre><br />
<definitions name="Stateful"<br />
targetNamespace="http://acme.org/sample" ...><br />
<br />
<types><br />
<xsd:schema targetNamespace="http://acme.org/sample"> <br />
<xsd:import namespace="http://gcube-system.org/namespaces/common/core/types" schemaLocation="../gcube/common/core/types/GCUBETypes.xsd"/><br />
<br />
<xsd:element name="aboutSF" type="coretypes:VOID" /><br />
<xsd:element name="aboutSFResponse" type="xsd:string" /> <br />
<br />
<xsd:element name="Name" type="xsd:string"/><br />
<xsd:element name="Visits" type="xsd:int"/><br />
<br />
<xsd:element name="StatefulResourceProperties"><br />
<xsd:complexType><br />
<xsd:sequence><br />
<xsd:element ref="tns:Name" minOccurs="1" maxOccurs="1"/><br />
<xsd:element ref="tns:Visits" minOccurs="1" maxOccurs="1"/><br />
</xsd:sequence><br />
</xsd:complexType><br />
</xsd:element> <br />
<br />
</xsd:schema><br />
</types><br />
</pre><br />
<br />
=== Port-Type definitions ===<br />
Extend the Stateful port-type with the GCUBEProvider and declare in the port-type definition the Resource Property document:<br />
<pre><br />
<portType name="StatefulPortType"<br />
wsrp:ResourceProperties="tns:StatefulResourceProperties"<br />
wsdlpp:extends="provider:GCUBEProvider"><br />
...<br />
</portType><br />
</pre><br />
<br />
=== Publication Profile ===<br />
Provide a Publication Profile:<br />
<pre><br />
<ServiceGroupRegistrationParameters<br />
xmlns:sgc="http://mds.globus.org/servicegroup/client"<br />
xmlns:xsd="http://www.w3.org/2001/XMLSchema"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"<br />
xmlns:agg="http://mds.globus.org/aggregator/types"<br />
xmlns="http://mds.globus.org/servicegroup/client"><br />
<br />
<br />
<!-- Specifies that the registration will be renewed every 30 seconds --><br />
<RefreshIntervalSecs>60</RefreshIntervalSecs><br />
<br />
<br />
<!-- <Content> specifies registration specific information --><br />
<Content xsi:type="agg:AggregatorContent"><br />
<br />
<agg:AggregatorConfig><br />
<agg:GetMultipleResourcePropertiesPollType xmlns:tutorial="http://acme.org/sample"><br />
<agg:PollIntervalMillis>60000</agg:PollIntervalMillis><br />
<agg:ResourcePropertyNames>tutorial:Name</agg:ResourcePropertyNames><br />
<agg:ResourcePropertyNames>tutorial:Visits</agg:ResourcePropertyNames><br />
</agg:GetMultipleResourcePropertiesPollType><br />
</agg:AggregatorConfig><br />
<br />
<agg:AggregatorData/><br />
<br />
</Content><br />
<br />
</ServiceGroupRegistrationParameters><br />
</pre><br />
Save the profile as '''registration.xml''' and place it in the etc folder under the service location: <br />
<pre><br />
|-SampleService<br />
|--etc<br />
|---profile.xml<br />
|---deploy-jndi-config.xml<br />
|---deploy-server.wsdd<br />
|---build.properties<br />
|---registration.xml<br />
|<br />
|--src<br />
|---<omissis><br />
|<br />
|--schema<br />
|---Stateless.wsdl<br />
|---Factory.wsdl<br />
|---Stateful.wsdl<br />
|<br />
|<br />
|--build.xml<br />
|<br />
|-Dependencies<br />
|--SampleService<br />
<br />
</pre><br />
Include the ''Publication Profile'' resource and the ''RPDName'' (Resource Property document name) in the stateful JNDI configuration:<br />
<pre><br />
<jndiConfig><br />
<br />
<omissis><br />
<service name="acme/sample/stateful"><br />
<br />
<environment <br />
name="RPDName"<br />
value="StatefulResourceProperties"<br />
type="java.lang.String"<br />
override="false"/> <br />
<br />
<resource name="publicationProfile" type="org.gcube.common.core.state.GCUBEPublicationProfile"> <br />
<resourceParams><br />
<parameter><br />
<name>factory</name><br />
<value>org.globus.wsrf.jndi.BeanFactory</value><br />
</parameter><br />
<parameter><br />
<name>mode</name><br />
<value>pull</value><br />
</parameter><br />
<parameter><br />
<name>fileName</name><br />
<value>registration.xml</value><br />
</parameter><br />
</resourceParams><br />
</resource><br />
<br />
<resource name="home" type="org.acme.sample.stateful.Home"><br />
<resourceParams> <br />
<parameter><br />
<name>factory</name><br />
<value>org.globus.wsrf.jndi.BeanFactory</value><br />
</parameter><br />
<parameter><br />
<name>resourceClass</name><br />
<value>org.acme.sample.stateful.Resource</value><br />
</parameter><br />
<parameter><br />
<name>persistenceDelegateClass</name><br />
<value>org.acme.sample.stateful.ResourcePersistenceDelegate</value><br />
</parameter><br />
</resourceParams><br />
</resource><br />
<br />
<environment <br />
name="frequentUserLimit" <br />
value="3" <br />
type="java.lang.Integer"<br />
override="false" /><br />
</service><br />
</jndiConfig><br />
</pre><br />
<br />
== How to persist the state ==<br />
The gCore Framework comes with a persistence mini-framework implementing <code>GCUBEStatefulResource</code> serialization and deserialization from/to some form of long-term storage. <br />
Since the most expected exploitation of the persistence is to serialise/deserialise the state of a <code>GCUBEWSResource</code>, the framework provides also some ready-to-use implementations of the abstract persistence delegate for <code>GCUBEWSResource</code> to perform file-based persistence. <br />
<br />
=== GCUBEFilePersistenceDelegate ===<br />
The root file-based persistence class (<code>GCUBEFilePersistenceDelegate</code>) is an abstract extension of a persistence delegate to add persistence to any <code>GCUBEStatefulResource</code> derived class.<br />
It configures the persistence storage folder as:<br />
''$HOME/.gcore/persisted/$Container.ID/$ServiceName/$Resource.class/$ResourceID.extension''<br />
It implements resource de/serialization by calling the Resource-specific <code>onLoad/onStore</code> methods<br />
It has been specialized by the following classes:<br />
* <code>GCUBELocalViewFilePersistenceDelegate</code><br />
* <code>GCUBELRFilePersistenceDelegate</code><br />
* <code>GCUBEWSFilePersistenceDelegate</code><br />
* <code>GCUBEWSLiteFilePersistenceDelegate</code><br />
<br />
To enable the persistence of a GCUBEWSResouce, a new class extending the <code>GCUBEWSFilePersistenceDelegate</code> has to be created:<br />
<pre><br />
package org.acme.sample.stateful;<br />
<br />
import java.io.ObjectInputStream;<br />
import java.io.ObjectOutputStream;<br />
<br />
<br />
import org.gcube.common.core.persistence.GCUBEWSFilePersistenceDelegate;<br />
<br />
public class ResourcePersistenceDelegate extends GCUBEWSFilePersistenceDelegate<Resource>{<br />
<br />
protected void onLoad(Resource resource,ObjectInputStream ois) throws Exception { <br />
super.onLoad(resource,ois);<br />
resource.setName((String)ois.readObject());<br />
resource.setVisits((Integer)ois.readObject());<br />
}<br />
<br />
protected void onStore(Resource resource,ObjectOutputStream oos) throws Exception { <br />
super.onStore(resource,oos);<br />
oos.writeObject(resource.getName());<br />
oos.writeObject(resource.getVisits());<br />
<br />
}<br />
}<br />
<br />
</pre><br />
<br />
Notes:<br />
* the class extends the <code>GCUBEWSFilePersistenceDelegate</code> class by parametrising the extension with the <code>Resource</code> class <br />
* the class implements the <code>onLoad()</code> and <code>onStore()</code> methods<br />
* as first step, they MUST call their <code>super</code> implementation<br />
* then, they store/load the <code>Resource</code> class state, i.e. the Name and Visits properties' values<br />
<br />
=== How to enable persistence ===<br />
As most of gCore Framework facilities, GCUBEResource Persistence can be enabled by modifying the gCube Service JNDI file by declaring in the Home resource the persistence delegate class to use:<br />
<pre><br />
<br />
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config"><br />
<br />
.....<br />
<br />
<service name="acme/sample/stateful"><br />
<br />
<environment <br />
name="RPDName"<br />
value="StatefulResourceProperties"<br />
type="java.lang.String"<br />
override="false"/> <br />
<br />
<resource name="home" type="org.acme.sample.stateful.Home"><br />
<resourceParams> <br />
<parameter><br />
<name>factory</name><br />
<value>org.globus.wsrf.jndi.BeanFactory</value><br />
</parameter><br />
<parameter><br />
<name>resourceClass</name><br />
<value>org.acme.sample.stateful.Resource</value><br />
</parameter><br />
<parameter><br />
<name>persistenceDelegateClass</name><br />
<value>org.acme.sample.stateful.ResourcePersistenceDelegate</value><br />
</parameter><br />
</resourceParams><br />
</resource><br />
</service><br />
</jndiConfig> <br />
</pre></div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=725Advanced Topics2008-06-06T18:03:58Z<p>Lucio.lelii: /* Sample usage */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see [[https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient#Implementation_Overview ExistClient]]<br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=724Advanced Topics2008-06-06T18:02:16Z<p>Lucio.lelii: /* Sample usage */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see the [[ https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient ExistClient ]]<br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=723Advanced Topics2008-06-06T17:59:14Z<p>Lucio.lelii: /* Sample usage */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
see the [[ https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/ExistClient | ExistClient Implementation]]<br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=656Advanced Topics2008-05-23T13:14:48Z<p>Lucio.lelii: /* Sample usage */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
The ISclient reference implementation makes use of Xquery Technology to query over the underneath Exist database.<br />
Client/services can prepare a custom xQuery over the DB and use the Generic Query object to excecute it and going through the result:<br />
<br />
<pre><br />
<br />
GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);<br />
query.setExpression("for $Profile in collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");<br />
List<XMLResult> result =client.execute(query, scope);<br />
for (String resultItem :result ) {<br />
System.out.println(resultItem.evaluate("an XPath ... ")); <br />
System.out.println(resultItem.toString());<br />
}<br />
<br />
</pre><br />
<br />
The GCUBEGeneric<br />
<br />
<br />
You can use a predefined ISQuery Object as well:<br />
<br />
<pre><br />
<br />
GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery query = client.getQuery(GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery.class); <br />
GCUBEWSProperty property = new GCUBEWSProperty("IndexTypeName","index_type_string_string");<br />
<br />
GCUBEWSProperty property2 = new GCUBEWSProperty("IndexID","999ba610-e9fb-11dc-b51b-84732c1e88f2");<br />
<br />
ArrayList <GCUBEWSProperty> properties = new ArrayList();<br />
properties.add(property);<br />
properties.add(property2);<br />
query.setPropertiesValuesAndNamespace(properties, "http://gcube-system.org/namespaces/index/ForwardIndexManagementService");<br />
<br />
List<EndpointReferenceType> result = client.execute(query, scope);<br />
<br />
for (EndpointReferenceType resultItem :result ) {<br />
System.out.println(resultItem.toString());<br />
<br />
} <br />
</pre><br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=655Advanced Topics2008-05-23T12:28:53Z<p>Lucio.lelii: /* ISClient interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIQuery queryRI = client.getQuery(GCUBERIQuery.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
The ISclient reference implementation makes use of Xquery Technology to query over the underneath Exist database.<br />
Client/services can prepare a custom xQuery over the DB and use the Generic Query object to excecute it and going through the result:<br />
<br />
<pre><br />
<br />
GCUBEGenericQuery query = client.getQuery(GCUBEGenericQuery.class);<br />
query.setExpression("for $Profile in collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");<br />
List<XMLResult> result =client.execute(query, scope);<br />
for (String resultItem :result ) {<br />
System.out.println(resultItem.evaluate("an XPath ... ")); <br />
System.out.println(resultItem.toString());<br />
}<br />
</pre><br />
<br />
You can use a predefined ISQuery Object as well:<br />
<br />
<pre><br />
<br />
GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery query = client.getQuery(GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery.class); <br />
GCUBEWSProperty property = new GCUBEWSProperty("IndexTypeName","index_type_string_string");<br />
<br />
GCUBEWSProperty property2 = new GCUBEWSProperty("IndexID","999ba610-e9fb-11dc-b51b-84732c1e88f2");<br />
<br />
ArrayList <GCUBEWSProperty> properties = new ArrayList();<br />
properties.add(property);<br />
properties.add(property2);<br />
query.setPropertiesValuesAndNamespace(properties, "http://gcube-system.org/namespaces/index/ForwardIndexManagementService");<br />
<br />
List<EndpointReferenceType> result = client.execute(query, scope);<br />
<br />
for (EndpointReferenceType resultItem :result ) {<br />
System.out.println(resultItem.toString());<br />
<br />
} <br />
</pre><br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.leliihttps://gcore.wiki.gcube-system.org/index.php?title=Advanced_Topics&diff=654Advanced Topics2008-05-23T10:57:05Z<p>Lucio.lelii: /* ISClient interface */</p>
<hr />
<div>== Interfacing the Information System ==<br />
<br />
The gCore Frameork has been designed to work independently from a IS specific Implementation.<br />
In order to let the gCF unbound from a IS, implementation both query & publishing interfaces have been<br />
designed.<br />
The gCF implements then a dynamic class loader that ( reading an implementation file that contains the mapping btw <br />
the IS interfaces and their implementations) can abstract over the IS technology.<br />
<br />
=== ISQuery interface ===<br />
<br />
The ISQuery interface designs the minimal query behavoiur accepted by the ISClient.<br />
The query contains the textual query expression and specify a time-to-live for their results <br />
(that can be exploited by future caching mechianism)<br />
The definition is parametric with respect the type of the exptected results.<br />
This is not required for the interface, though it may for its implementations; in addition , it allows full typing <br />
of the ISClient interface.<br />
<br />
<pre><br />
public interface ISQuery<RESULT> {<br />
/**<br />
* Returns the time-to-live of the results of the query.<br />
* @return the time-to-live.<br />
*/<br />
public long getTTL();<br />
<br />
/**<br />
* Sets the time-to-live of the results of the query.<br />
* @param ttl the time-to-live.<br />
*/<br />
public void setTTL(long ttl);<br />
<br />
/**<br />
* Returns the textual expression of the query.<br />
* @return the expression.<br />
*/<br />
public String getQueryExpression();<br />
<br />
/**<br />
* Sets the textual expression of the query.<br />
* @param exp the expression.<br />
*/<br />
public void setQueryExpression(String exp);<br />
}<br />
</pre><br />
<br />
=== ISClient interface ===<br />
<br />
The IS Client interface defines only two methods:<br />
<br />
<pre><br />
public <RESULT> List<RESULT> execute(ISQuery<RESULT> query, GCUBEScope scope,GCUBEContext ...context) throws <br />
<br />
ISMalformedQueryException,ISInvalidQueryException,ISException; <br />
</pre><br />
<br />
<br />
The execute method takes as parameter:<br />
*the ISQuery Object (with all parameters filled correctly otherwise the ISClient throws an ISMalformedQueryException);<br />
*a GCUBEScope object that specifies the query scope;<br />
*The GCUBEContext of the caller ( in case of a gCube Service the caller Context is the Service Context itself);<br />
<br />
The return type is a List object specified as Type parameter in the related ISquery object.<br />
<br />
In order to get the implementation of the ISClient Interface, the GHNContext exposes the static method getImplementation:<br />
<br />
<pre><br />
ISClient client = GHNContext.getImplementation(ISClient.class);<br />
</pre><br />
<br />
The IS Client Interface predefines a list of abstract queries that model the queries used by the gCF.<br />
<br />
In particular we have general queries over GCUBEResources:<br />
<br />
*GCUBECollectionQuery<br />
*GCUBECSInstanceQuery<br />
*GCUBECSQuery<br />
*GCUBEExternalRIQuery<br />
*GCUBEGenericResourceQuery<br />
*GCUBEGHNQuery<br />
*GCUBEMCollectionQuery<br />
*GCUBERIQuery<br />
*GCUBEServiceQuery<br />
*GCUBETPQuery<br />
*GCUBEVREQuery<br />
<br />
<br />
Queries over GCUBEWSResource:<br />
<br />
*WSResourceQuery<br />
<br />
Generic queries:<br />
<br />
*GCUBEGenericQuery<br />
<br />
<br />
In order to get the implementation specific ISQuery Object, IS Client exposes the method getQuery, that dynamically loads the ISQuery implementation of the given ISQuery interface:<br />
<br />
<pre><br />
public <RESULT, QUERY extends ISQuery<RESULT>> QUERY getQuery(Class<QUERY> clazz) throws ISUnsupportedQueryException;<br />
</pre><br />
<br />
i.e.<br />
<br />
<pre><br />
GCUBERIsFromClassAndName queryRI = client.getQuery(GCUBERIsFromClassAndName.class);<br />
</pre><br />
<br />
<br />
==== Sample usage ====<br />
<br />
The ISclient reference implementaiton makes use of Xquery Technology to query over the underneath Exist database.<br />
Client/services can prepare a custom xQuery over the DB and use the Generic Query object to exceute it:<br />
<br />
<pre><br />
<br />
GenericQuery query = client.getQuery(GenericQuery.class);<br />
query.setQueryExpression("for $Profile in <br />
<br />
collection(\"/db/Profiles\")//Document/Data/child::*[local-name()='Profile']/Resource return $Profile/UniqueID");<br />
List<String> result =client.execute(query, scope);<br />
for (String resultItem :result ) {<br />
System.out.println(resultItem);<br />
}<br />
</pre><br />
<br />
You can use a predefined ISQuery Object as well:<br />
<br />
<pre><br />
<br />
GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery query = client.getQuery(GCUBEWSResourceEPRFromRPValuesAndNamespaceQuery.class); <br />
GCUBEWSProperty property = new GCUBEWSProperty("IndexTypeName","index_type_string_string");<br />
<br />
GCUBEWSProperty property2 = new GCUBEWSProperty("IndexID","999ba610-e9fb-11dc-b51b-84732c1e88f2");<br />
<br />
ArrayList <GCUBEWSProperty> properties = new ArrayList();<br />
properties.add(property);<br />
properties.add(property2);<br />
query.setPropertiesValuesAndNamespace(properties, "http://gcube-system.org/namespaces/index/ForwardIndexManagementService");<br />
<br />
List<EndpointReferenceType> result = client.execute(query, scope);<br />
<br />
for (EndpointReferenceType resultItem :result ) {<br />
System.out.println(resultItem.toString());<br />
<br />
} <br />
</pre><br />
<br />
<br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 17:09, 31 March 2008 (EEST)<br />
<br />
=== ISPublisher interface ===<br />
<br />
The ISPublisher interface defines methods to register/unregister/update these kind of objects on the IS:<br />
<br />
*GCUBEResources<br />
*GCUBEWSResources<br />
*Topics <br />
<br />
In particular GCUBEResources profiles are modeled as java classes inside the framework:<br />
*GCUBEService<br />
*GCUBERunningInstance<br />
*GCUBEHostingNode<br />
*GCUBECS<br />
*GCUBECSInstance<br />
*GCUBECollection<br />
*GCUBEMCollection<br />
*GCUBEVRE<br />
*GCUBETransformationProgram<br />
*GCUBEExternalRunningInstance<br />
*GCUBEGenericRescource<br />
<br />
gCUBE Client/Services can explout the IS-Publisher to store/update/remove GCUBEResource profiles from/to the IS:<br />
<br />
<pre><br />
<br />
/**<br />
* Register a GCUBEResource on the Information System<br />
*<br />
* @param resource The Gcube Resource to register<br />
* @param scope the Gcube scope to use<br />
* @return the Registered GCUBEResource profile<br />
* @throws ISPublisherException Exception<br />
*/<br />
<br />
public String registerGCUBEResource(GCUBEResource resource,GCUBEScope scope, GCUBESecurityManager manager)throws <br />
<br />
GCUBEPublisherException;<br />
<br />
/**<br />
* Remove a GCUBEResource from the Information System<br />
*<br />
* @param ID the ID related to the Gcube Resource to remove<br />
* @param the GCUBEResource type to remove<br />
* @param scope the registration scope<br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeGCUBEResource(String ID,String type,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Update a GCUBEResource in the Information System<br />
<br />
* @param resource The new Gcube Resource to update <br />
* @param manager a GCUBESecurityManager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void updateGCUBEResource(GCUBEResource resource,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
<br />
GCUBEWSResource class then, defines WS-Resource-Properties to publish to the IS ( the publication mechanism is completely<br />
hidden by the gCF). The gCF exploits these mothods to implement the WS-Resource-Properties registration/unregistation from/to IS:<br />
<br />
<pre><br />
/**<br />
* Enables WS-resource registration on a Information System<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Enables WS-resource registration on a Information System( named Registration)<br />
* <br />
* @param resource The Gcube WSResouce to register<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes the registration of a GCube WS-Resource from the InformationSystem<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
/**<br />
* Removes he registration of a GCube WS-Resource from the InformationSystem( named registration)<br />
*<br />
* @param resource The Gcube WSResouce to unregister<br />
* @param name the name associated to the registration<br />
* @param scope optional scope (overrides the scope specified by the GCUBEWSResource) <br />
* @throws ISPublisherException Exception<br />
*/<br />
public void removeWSResource(GCUBEWSResource resource, String name,GCUBEScope ...scope) throws ISPublisherException;<br />
<br />
</pre><br />
<br />
Topics publishers can use the IS-Publihser interface, to let their topics being published on the IS and subscribed for <br />
notification to.<br />
<br />
<pre><br />
/**<br />
* Register the given topics belonging to the given source EPR as a Notification Producer inside the IS Notification<br />
* <br />
* @param sourceEpr The notification producer EPR<br />
* @param topicsList The list of topic to register<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void registerToISNotification(EndpointReferenceType sourceEpr, ArrayList<QName> topicsList,GCUBEScope <br />
<br />
scope,GCUBESecurityManager manager) throws ISPublisherException;<br />
<br />
/**<br />
* Unregister the given topics belonging to the given source EPR from the IS Notification<br />
* <br />
* @param sourceEpr the notification producer EPR<br />
* @param topicsList The list of topic to unregister<br />
* @param scope the Scope of the caller<br />
* @param manager GCUBESecurityManager manager<br />
* @throws ISPublisherException Exception<br />
*/<br />
public void unregisterFromISNotification(EndpointReferenceType sourceEpr, <br />
<br />
ArrayList<QName> topicsList,GCUBEScope scope,GCUBESecurityManager manager) throws ISPublisherException ;<br />
<br />
</pre><br />
<br />
The ISPublisher methods take as parameters the GCUBEScope and the GCUBESecurityManager of the caller in order to<br />
prepare the IS Services stubs with the correct Scope and security Settings.<br />
<br />
==== Sample usage ====<br />
<br />
In Order to get the ISPublisher implementation object from its itnerface ( as for the ISClient), the GHNContext offers the<br />
getImplementation method:<br />
<br />
<pre><br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
</pre><br />
<br />
In order to register a GCUBEResource profile ( i.e. a GCUBEService) on the IS, this is the sample code:<br />
<br />
<pre><br />
FileReader fis = new FileReader (args[0]);<br />
GCUBEService resource =GHNContext.getImplementation(GCUBEService.class);<br />
resource.load(fis);<br />
GCUBESecurityManagerImpl managerSec = new GCUBESecurityManagerImpl() { public boolean isSecurityEnabled() {return true;}};<br />
GSSCredential cred =org.diligentproject.dvos.authentication.util.ProxyUtil.loadProxyCredentials(args[1]);<br />
managerSec.useCredentials(cred);<br />
ISPublisher publisher =GHNContext.getImplementation(ISPublisher.class);<br />
publisher.registerGCUBEResource(resource, GCUBEScope.getScope("/gcube/devsec"), managerSec);<br />
</pre><br />
<br />
--[[User:Andrea.manzi|Andrea.manzi]] 18:08, 31 March 2008 (EEST)<br />
<br />
== Service security == <br />
<br />
=== Configuring gContainer with Security ===<br />
<br />
=== Configuring gCube Service with Credentials ===<br />
<br />
--[[User:Manuele.simi|Manuele.simi]] 20:11, 28 March 2008 (EET)</div>Lucio.lelii