ome.api
Interface IShare

All Superinterfaces:
ServiceInterface
All Known Subinterfaces:
LocalShare
All Known Implementing Classes:
ShareBean

public interface IShare
extends ServiceInterface

Provides method for sharing - collaboration process for images, datasets, projects.

Since:
3.0-Beta4
Author:
Aleksandra Tarkowska, aleksandrat at lifesci.dundee.ac.uk, Josh Moore, josh at glencoesoftware.com

Method Summary
 void activate(long shareId)
          Turns on the access control lists attached to the given share for the current session.
 ome.model.annotations.CommentAnnotation addComment(long shareId, String comment)
          Creates comment for share.
 void addGuest(long shareId, String emailAddress)
          Add guest email address to the share.
 void addGuests(long shareId, String... emailAddresses)
          Adds guest email addresses to the share.
<T extends ome.model.IObject>
void
addObject(long shareId, T object)
          Adds new item to share.
<T extends ome.model.IObject>
void
addObjects(long shareId, T... objects)
          Adds new items to share.
 ome.model.annotations.CommentAnnotation addReply(long shareId, String comment, ome.model.annotations.CommentAnnotation replyTo)
          Creates comment which replies to an existing comment.
 void addUser(long shareId, ome.model.meta.Experimenter exp)
          Adds experimenter to share
 void addUsers(long shareId, ome.model.meta.Experimenter... exps)
          Adds experimenters to share
 void closeShare(long shareId)
          Closes share.
<T extends ome.model.IObject>
long
createShare(String description, Timestamp expiration, List<T> items, List<ome.model.meta.Experimenter> exps, List<String> guests, boolean enabled)
          Creates share with all related: items, members, and guests.
 void deactivate()
          Turns off the access control lists with the current share.
 void deleteComment(ome.model.annotations.Annotation comment)
          Deletes comment from the database.
 Map<String,ome.model.meta.Experimenter> getActiveConnections(long shareId)
          Gets actual active connections to share.
 Set<String> getAllGuests(long shareId)
          Get the email addresses for all share guests.
 Set<ome.model.meta.Experimenter> getAllMembers(long shareId)
          Get all users who are a member of the share.
 Set<String> getAllUsers(long shareId)
          Get a single set containing the login names of the Experimenters as well email addresses for guests.
 Map<Long,Long> getCommentCount(Set<Long> shareIds)
          Returns a map from share id to comment count.
 List<ome.model.annotations.Annotation> getComments(long shareId)
          Looks up all comments which belong to the share.
<T extends ome.model.IObject>
Map<Class<T>,List<Long>>
getContentMap(long shareId)
          Returns the contents of the share keyed by type.
<T extends ome.model.IObject>
List<T>
getContents(long shareId)
          Looks up all items belong to the share.
 int getContentSize(long shareId)
          Returns the number of items in the share.
<T extends ome.model.IObject>
List<T>
getContentSubList(long shareId, int start, int finish)
          Returns a range of items from the share.
 List<ome.model.meta.Event> getEvents(long shareId, ome.model.meta.Experimenter experimenter, Timestamp from, Timestamp to)
          Gets events for share per experimenter for period of time.
 Map<Long,Long> getMemberCount(Set<Long> shareIds)
          Returns a map from share id to the count of total members (including the owner).
 Set<ome.model.meta.Session> getMemberShares(boolean onlyActive)
          Gets all shares where current Experimenter is a member.
 Set<ome.model.meta.Session> getMemberSharesFor(ome.model.meta.Experimenter user, boolean onlyActive)
          Gets all shares where given Experimenter is a member.
 Set<ome.model.meta.Session> getOwnShares(boolean onlyActive)
          Gets all owned shares for the current Experimenter
 Map<String,ome.model.meta.Experimenter> getPastConnections(long shareId)
          Gets previous connections to share.
 ome.model.meta.Share getShare(long sessionId)
          Gets a share as a Session with all related: comments, members, fully loaded.
 Set<ome.model.meta.Session> getSharesOwnedBy(ome.model.meta.Experimenter user, boolean onlyActive)
          Gets all shares owned by the given Experimenter.
 void invalidateConnection(long shareId, ome.model.meta.Experimenter exp)
          Makes the connection invalid for share for specifiec user.
 void removeGuest(long shareId, String emailAddress)
          Removes guest email address from share.
 void removeGuests(long shareId, String... emailAddresses)
          Removes guest email addresses from the share.
<T extends ome.model.IObject>
void
removeObject(long shareId, T object)
          Removes existing item from the share.
<T extends ome.model.IObject>
void
removeObjects(long shareId, T... objects)
          Remove existing items from the share.
 void removeUser(long shareId, ome.model.meta.Experimenter exp)
          Removes experimenter from share
 void removeUsers(long shareId, List<ome.model.meta.Experimenter> exps)
          Removes experimenters from share
 void setActive(long shareId, boolean active)
           
 void setDescription(long shareId, String description)
           
 void setExpiration(long shareId, Timestamp expiration)
           
 

Method Detail

activate

void activate(long shareId)
Turns on the access control lists attached to the given share for the current session. Warning: this will slow down the execution of the current session for all database reads. Writing to the database will not be allowed. If share does not exist or is not accessible (non-members) or is disabled, then an ValidationException is thrown.

Parameters:
shareId -

deactivate

void deactivate()
Turns off the access control lists with the current share.


getCommentCount

Map<Long,Long> getCommentCount(Set<Long> shareIds)
Returns a map from share id to comment count.

Parameters:
shareIds - Not null.
Returns:
Map with all ids present and 0 if no count exists.
Throws:
ome.conditions.ValidationException - if a given share does not exist

getOwnShares

Set<ome.model.meta.Session> getOwnShares(boolean onlyActive)
Gets all owned shares for the current Experimenter

Parameters:
onlyActive - if true, then only shares which can be used for login will be returned. All "draft" shares (see createShare(String, Timestamp, List, List, List, boolean) and closed shares will be filtered.
Returns:
set of shares. Never null. May be empty.

getMemberShares

Set<ome.model.meta.Session> getMemberShares(boolean onlyActive)
Gets all shares where current Experimenter is a member.

Parameters:
onlyActive - if true, then only shares which can be used for login will be returned. All "draft" shares (see createShare(String, Timestamp, List, List, List, boolean) and closed shares will be filtered.
Returns:
set of shares. Never null. May be empty.

getSharesOwnedBy

Set<ome.model.meta.Session> getSharesOwnedBy(ome.model.meta.Experimenter user,
                                             boolean onlyActive)
Gets all shares owned by the given Experimenter.

Parameters:
onlyActive - if true, then only shares which can be used for login will be returned. All "draft" shares (see createShare(String, Timestamp, List, List, List, boolean) and closed shares will be filtered.
Returns:
set of shares. Never null. May be empty.

getMemberSharesFor

Set<ome.model.meta.Session> getMemberSharesFor(ome.model.meta.Experimenter user,
                                               boolean onlyActive)
Gets all shares where given Experimenter is a member.

Parameters:
onlyActive - if true, then only shares which can be used for login will be returned. All "draft" shares (see createShare(String, Timestamp, List, List, List, boolean) and closed shares will be filtered.
Returns:
set of shares. Never null. May be empty.

getShare

ome.model.meta.Share getShare(long sessionId)
Gets a share as a Session with all related: comments, members, fully loaded. Unlike the other methods on this interface, if the sessionId is unknown, does not throw a ValidationException.

Parameters:
sessionId -
Returns:
a Session with id and Details set or null. The owner in the Details object is the true owner, and the group in the Details has all member users linked. Annotation instances of the share are linked to the Session. Missing is a list of share guests.

getContents

<T extends ome.model.IObject> List<T> getContents(long shareId)
Looks up all items belong to the share.

Parameters:
shareId -
Returns:
list of objects. Not null. Probably not empty.

getContentSubList

<T extends ome.model.IObject> List<T> getContentSubList(long shareId,
                                                        int start,
                                                        int finish)
Returns a range of items from the share.

See Also:
getContents(long)

getContentSize

int getContentSize(long shareId)
Returns the number of items in the share.


getContentMap

<T extends ome.model.IObject> Map<Class<T>,List<Long>> getContentMap(long shareId)
Returns the contents of the share keyed by type.


createShare

<T extends ome.model.IObject> long createShare(String description,
                                               Timestamp expiration,
                                               List<T> items,
                                               List<ome.model.meta.Experimenter> exps,
                                               List<String> guests,
                                               boolean enabled)
Creates share with all related: items, members, and guests.

Parameters:
description -
expiration -
exps -
guests -
enabled - if true, then the share is immediately available for use. If false, then the share is in draft state. All methods on this interface will work for shares except activate(long). Similarly, the share password cannot be used by guests to login.

setDescription

void setDescription(long shareId,
                    String description)

setExpiration

void setExpiration(long shareId,
                   Timestamp expiration)

setActive

void setActive(long shareId,
               boolean active)

closeShare

void closeShare(long shareId)
Closes share. No further logins will be possible and all getters (e.g. #getMemberShares(boolean), {@link #getAllShares(boolean), ...} will filter these results if "onlyActive" is true.

Parameters:
shareId -

addObjects

<T extends ome.model.IObject> void addObjects(long shareId,
                                              T... objects)
Adds new items to share. Conceptually calls addObjects(long, IObject...) for every argument passed, but the graphs will be merged.

Parameters:
shareId -
objects -

addObject

<T extends ome.model.IObject> void addObject(long shareId,
                                             T object)
Adds new item to share. The entire object graph with the exception of all Details will be loaded into the share. If you would like to load a single object, then pass an unloaded reference.

Parameters:
shareId -
object -

removeObjects

<T extends ome.model.IObject> void removeObjects(long shareId,
                                                 T... objects)
Remove existing items from the share.

Parameters:
shareId -
objects -

removeObject

<T extends ome.model.IObject> void removeObject(long shareId,
                                                T object)
Removes existing item from the share.

Parameters:
share -
item -

getComments

List<ome.model.annotations.Annotation> getComments(long shareId)
Looks up all comments which belong to the share.

Parameters:
share -
Returns:
list of Annotation

getMemberCount

Map<Long,Long> getMemberCount(Set<Long> shareIds)
Returns a map from share id to the count of total members (including the owner). This is represented by ShareMember links.

Parameters:
shareIds - Not null.
Returns:
Map with all ids present.
Throws:
ome.conditions.ValidationException - if a given share does not exist

addComment

ome.model.annotations.CommentAnnotation addComment(long shareId,
                                                   String comment)
Creates comment for share.

Parameters:
share -
comment -

addReply

ome.model.annotations.CommentAnnotation addReply(long shareId,
                                                 String comment,
                                                 ome.model.annotations.CommentAnnotation replyTo)
Creates comment which replies to an existing comment.

Parameters:
shareId -
comment -
replyTo -
Returns:

deleteComment

void deleteComment(ome.model.annotations.Annotation comment)
Deletes comment from the database.

Parameters:
comment -

getAllMembers

Set<ome.model.meta.Experimenter> getAllMembers(long shareId)
Get all users who are a member of the share.


getAllGuests

Set<String> getAllGuests(long shareId)
Get the email addresses for all share guests.


getAllUsers

Set<String> getAllUsers(long shareId)
                        throws ome.conditions.ValidationException
Get a single set containing the login names of the Experimenters as well email addresses for guests.

Parameters:
shareId -
Returns:
Throws:
ome.conditions.ValidationException - if there is a conflict between email addresses and user names.

addUsers

void addUsers(long shareId,
              ome.model.meta.Experimenter... exps)
Adds experimenters to share

Parameters:
share -
exps -

addGuests

void addGuests(long shareId,
               String... emailAddresses)
Adds guest email addresses to the share.

Parameters:
shareId -
emailAddresses -

removeUsers

void removeUsers(long shareId,
                 List<ome.model.meta.Experimenter> exps)
Removes experimenters from share

Parameters:
shareId -
exps -

removeGuests

void removeGuests(long shareId,
                  String... emailAddresses)
Removes guest email addresses from the share.

Parameters:
shareId -
exp -

addUser

void addUser(long shareId,
             ome.model.meta.Experimenter exp)
Adds experimenter to share

Parameters:
shareId -
exps -

addGuest

void addGuest(long shareId,
              String emailAddress)
Add guest email address to the share.

Parameters:
shareId -
emailAddress -

removeUser

void removeUser(long shareId,
                ome.model.meta.Experimenter exp)
Removes experimenter from share

Parameters:
shareId -
exps -

removeGuest

void removeGuest(long shareId,
                 String emailAddress)
Removes guest email address from share.

Parameters:
shareId -
emailAddress -

getActiveConnections

Map<String,ome.model.meta.Experimenter> getActiveConnections(long shareId)
Gets actual active connections to share.

Parameters:
shareId -
Returns:
map of experimenter and IP address

getPastConnections

Map<String,ome.model.meta.Experimenter> getPastConnections(long shareId)
Gets previous connections to share.

Parameters:
shareId -
Returns:
map of experimenter and IP address

invalidateConnection

void invalidateConnection(long shareId,
                          ome.model.meta.Experimenter exp)
Makes the connection invalid for share for specifiec user.

Parameters:
shareId -
exp - - connection

getEvents

List<ome.model.meta.Event> getEvents(long shareId,
                                     ome.model.meta.Experimenter experimenter,
                                     Timestamp from,
                                     Timestamp to)
Gets events for share per experimenter for period of time.

Parameters:
shareId -
exp -
from - - time
to - - time
Returns:
List of events


OmeroJava Api

Version: 4.3.3-00d1137e-b2894

Copyright © 2009 The University of Dundee. All Rights Reserved.