| /* $Id$ |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| module org.apache.etch.services.ns |
| |
| /** |
| * The NameService provides translation from an abstract name for a service to a |
| * uri that may be used to contact the service. A given service may offer |
| * several different connection schemes, and a client may only support a subset |
| * of those. So, when a client wishes to connect to a service, it may query |
| * the NameService with both abstract name and desired schemes in order to find |
| * a suitable match. |
| * |
| * Some example queries: |
| * |
| * All services with servicename='Foo' and instancename='bar' and qualifier='tcp' |
| * |
| * sourceUri='Foo/bar/tcp' |
| * |
| * Same as the query above, but written out longhand: |
| * |
| * servicename='Foo' and instancename='bar' and qualifier='tcp' |
| * |
| * Fully qualified sourceUri: |
| * |
| * sourceUri='Foo/bar/tcp/1' |
| * |
| * Any instance of service Foo located in Austin, TX: |
| * |
| * servicename='Foo' and qualities.location='Austin, TX' |
| * |
| * Instances of service Foo with capacity >= 400: |
| * |
| * servicename='Foo' and qualities.capacity>=400 |
| * |
| * Relative operations on qualities require that the quality be present and be |
| * comparable (with mixed types some type promotion is supported). But you might |
| * be surprised, qualities which are absent will give a negative comparison no |
| * matter which sense is used: both qualities.x > 50 and qualities.x < 50 are |
| * false whenever qualities.x is null. Consider this test: not qualities.x < 50. |
| * This is not the same as qualities.x >= 50. It is the same as qualities.x = |
| * null or qualities.x >= 50. |
| */ |
| @Timeout( 30000 ) |
| service NameService |
| { |
| /** An entry describing a service. */ |
| struct Entry |
| ( |
| /** A service description uri, composed of |
| * servicename/instancename/qualifier[/priority]. */ |
| string sourceUri, |
| |
| /** Qualities of this service instance. */ |
| Map qualities, |
| |
| /** Etch service connection uri, for example |
| * tcp://localhost:9000?filter=KeepAlive */ |
| string targetUri, |
| |
| /** Lifetime in seconds from last update. */ |
| int ttl, |
| |
| /** Who created or last update. */ |
| string who, |
| |
| /** Date / time of create or last update. */ |
| Datetime lastUpdate, |
| |
| /** Flag indicating entry has been removed. */ |
| boolean removed |
| ) |
| |
| /** |
| * Look up an entry by matching it against the sourceUri. |
| * |
| * @param source source uri |
| * |
| * @return entry matching the source uri. In the case of an |
| * absent instance name or qualifier, the implementation |
| * can decide which Entry to return. |
| */ |
| @Authorize( canLookup, source ) |
| Entry lookup( string source ) |
| |
| /** |
| * Looks up entries by matching them against the query string. Entries are |
| * returned in a stable and consistent order, increasing alphabetical by |
| * servicename, instancename, and scheme, and then increasing numerical by |
| * priority. If a scheme search term appears with a list, schemes are |
| * returned in the specified order (e.g., scheme='tls,tcp'). |
| * |
| * @param query a sql-like query expression using the elements of the |
| * sourceUri, targetUri, and qualities. If query is null or the empty |
| * string, all entries are matched. |
| * |
| * @param offset offset in the list of matched items of the first item to |
| * return. This parameter and the count parameter are used to step through |
| * the result set when there are many results. |
| * |
| * @param count number of items to return. |
| * |
| * @return entries matching query. If you requested 10 items and 10 are |
| * returned, there could be more. To get the next batch, add results.length |
| * to offset and call find again: |
| * |
| * int i = 0; |
| * int n = 10; |
| * Entry[] results; |
| * while ((results = service.find( null, i, n )).length > 0) |
| * { |
| * for (Entry e: results) |
| * processEntry( e ); |
| * if (results.length < n) |
| * break; |
| * i += results.length; |
| * } |
| */ |
| @Authorize( canFind, query ) |
| Entry[] find( string query, int offset, int count ) |
| |
| /** |
| * Adds or updates the specified entry. The given parameters replace any |
| * existing values in an Entry whose key is sourceUri, whereas who and |
| * lastUpdate are set to the current user and current date / time, |
| * respectively. |
| * |
| * @param sourceUri the uri describing the service. The uri should be of |
| * the form "servicename/instancename/scheme[/priority]", where servicename |
| * is a valid fully qualified service name (e.g., |
| * etch.services.ns.NameService"), instancename is a valid etch identifier |
| * (e.g, fred, alice01), scheme is a valid uri scheme (e.g., tcp, tls), and |
| * priority is an integer >= 1. If priority is omitted, it is defaulted to |
| * 1. |
| * |
| * @param qualities a map which may be used to describe additional features |
| * of the entry, such as purpose, licenses, capacity, location, owner, |
| * whatever. Query strings may test values of qualities using a variety of |
| * sql-like operators. Qualities may be null. |
| * |
| * @param targetUri the uri describing the contact information for the |
| * service. |
| * |
| * @param ttl the lifetime of the entry specified as seconds. 0 means |
| * forever, -1 means remove immediately when the connection to the |
| * NameService is dropped. |
| */ |
| @Authorize( canRegister, sourceUri, qualities, targetUri ) |
| void register( string sourceUri, Map qualities, string targetUri, int ttl ) |
| |
| /** |
| * Registers a number of entries all in one operation. Identical to calling |
| * register with each entry in turn. |
| * |
| * @param entries a sequence of Entry records with sourceUri, targetUri, |
| * qualities, and ttl as specified in register() above. Who and lastUpdate |
| * fields are ignored. |
| */ |
| @Authorize( canRegisterBulk, entries ) |
| void registerBulk( Entry[] entries ) |
| |
| /** |
| * Removes the specified entry. |
| * |
| * @param sourceUri the uri describing the service. |
| */ |
| @Authorize( canUnregister, sourceUri, deleteEntry ) |
| void unregister( string sourceUri, boolean deleteEntry ) |
| |
| /** |
| * Adds a request for notification of changes to entries matching the query. |
| * The current value of all matching entries is delivered via entryChanged |
| * client message, as well as any updates or new entries. |
| * |
| * @param query a sql-like query expression using the elements of the |
| * sourceUri, targetUri, and qualities. If query is null or the empty |
| * string, all entries are matched. |
| */ |
| @Authorize( canFind, query ) |
| void subscribe( string query ) |
| |
| /** |
| * Removes a request for notification of changes to entries matching the |
| * query. |
| * |
| * @param query a query previously passed to subscribe. The string must |
| * match exactly. |
| */ |
| void unsubscribe( string query ) |
| |
| /** |
| * Removes all requests for notification of changes to entries. This |
| * operation is implicitly performed when the connection to the NameService |
| * is dropped. |
| */ |
| void unsubscribeAll() |
| |
| //////////////////// |
| // RIGHTS TESTING // |
| //////////////////// |
| |
| /** |
| * Tests whether the current user is authorized to lookup the source. |
| * @param source the complete specification api/instance/scheme. |
| */ |
| boolean canLookup( string source ) |
| |
| /** |
| * Tests whether the current user is authorized to run the query. |
| * |
| * @param query a sql-like query expression using the elements of the |
| * sourceUri, targetUri, and qualities. If query is null or the empty |
| * string, all entries are matched. |
| * |
| * @return true if the current user is authorized to run the query. |
| */ |
| boolean canFind( string query ) |
| |
| /** |
| * Tests whether the current user is authorized to register the service. |
| * |
| * @param sourceUri the uri describing the service. |
| * |
| * @param qualities a map which may be used to describe additional features |
| * of the entry. |
| * |
| * @param targetUri the actual uri of the service |
| * |
| * @return true if the current user is authorized to register the service. |
| */ |
| boolean canRegister( string sourceUri, Map qualities, string targetUri ) |
| |
| /** |
| * Tests whether the current user is authorized to unregister the service. |
| * |
| * @param sourceUri the uri describing the service. |
| * |
| * @param deleteEntry if true, the entire entry matching the sourceUri |
| * would be deleted. if false, only the target uri matching the sourceUri |
| * would be deleted, but the entry would be intact. |
| * |
| * @return true if the current user is authorized to register the service. |
| */ |
| boolean canUnregister( string sourceUri, boolean deleteEntry ) |
| |
| |
| /** |
| * Tests whether the current user is authorized to register the entries. |
| * This is the same as: |
| * |
| * for (Entry entry: entries) |
| * if (!canRegister( entry.sourceUri, entry.qualities )) |
| * return false; |
| * return true; |
| * |
| * @param entries a sequence of Entry records with sourceUri, targetUri, |
| * qualities, and ttl as specified in register() above. Who and lastUpdate |
| * fields are ignored. |
| * |
| * @return true if the current user is authorized to register the entries. |
| * This is an all or nothing proposition. |
| */ |
| boolean canRegisterBulk( Entry[] entries ) |
| |
| //////////////////// |
| // CLIENT METHODS // |
| //////////////////// |
| |
| /** |
| * Notifies the client of a change in an entry. The entry might have been |
| * created, updated, or removed. |
| * |
| * Note: while this might have normally been an event, we made it a call |
| * to slow down the processing of what might otherwise be a rather large |
| * change set. |
| * |
| * Note: when keeping track of entries, always keep the one with the latest |
| * lastUpdate. |
| * |
| * @param query the query which triggered the notification. |
| * |
| * @param entry the entry which has changed. |
| */ |
| @Direction( client ) |
| void entryChanged( string query, Entry entry ) |
| } |