namespace java eu.dnetlib.r2d2.thrift
namespace rb ScholarlynkThrift

typedef string Url

struct User {
  1: string id,
  2: string name,
  6: string uid,
  7: string mail,
  3: string avatarUrl,
  4: string institutionId,
  5: string institutionName
}

struct UserResults {
  // -1 is unknown
  1: i32 count,
  2: list<User> items,
}

struct UserRef {
  1: string id,
  2: string name,
  3: string avatarUrl
}

struct Group {
	1: string id,
	2: string name,
	3: string description,
	4: i32 numberOfMembers,
	5: Url avatarUrl,
}

struct GroupResults {
  1: i32 count,
  2: list<Group> items,
}

struct Author {
  1: string id,
  2: string name,
  3: string originalName
}

struct Item {
  1: string id,
  2: string title,
  3: list<Author> authors,
  5: Url iconUrl,
  6: Url itemUrl,
  7: string description,
  8: string publisher
  /** 
   * it's the rating 
   * of the reading list in the context of the user's MVL (global to a user) 
   */
  9: double userRating,
  /**
   * average (perhaps weighted) of all the ratings of all the users for this reading list
   */
  10: double globalRating,
  11: list<UserRef> sharedWith,
  12: string publishedDate
}

struct ItemResults {
  1: i32 count,
  2: list<Item> items,
}


struct AccessTime {
  1: string creationDate
  2: string lastAccessDate
  3: string lastModificationDate
}

struct ReadingList {
  1: string id,
  2: string name,
  3: string description,
  4: UserRef owner,
  5: string iconUrl,
  6: i32 memberCount,
  7: i32 entryCount, // read only
  8: AccessTime accessTime,
  /** Should be called "user rating", since it's the rating 
   * of the reading list in the context of the user's MVL (global to a user) */
  9: double rating,
  /** average (perhaps weighted) of all the ratings of all the users for this reading list*/
  10: double globalRating,
  11: list<UserRef> sharedWith
}

struct ReadingListResults {
  1: i32 count,
  2: list<ReadingList> items
}

/**
 * Either an item or a reading list. Thrift lacks polymorphism, so we need this union type.
 */ 
struct InformationObject {
  1: Item item,
  2: ReadingList readingList
}

/**
 * This is the entry bean returned by getEntries
 * Each entry has a low level rating which is the rating 
 * of the given IO in the context of the reading list.
 *
 * Probably it's not the same rating that will be displayed in the 
 * final UI, since there we probably want the user's rating.
 */ 
struct RLEntry {
  1: string id,
  2: InformationObject io,
  3: list<string> tags,
  5: double rating
}

struct RLEntryDescription {
  1: string id, 
  2: string readingListId,
  3: string ioId,
  4: double rating
  // other stuff here
}

enum RLEntryFilter {
  ALL = 1,
  ITEMS_ONLY = 2,
  READING_LISTS_ONLY = 3,
  TOP_LEVEL_READING_LISTS_ONLY = 4
  
}

struct SearchResultEntry {
  1: RLEntryDescription entry,
  2: ReadingList readingList,
  3: list<string> tags
}

struct RLEntryResults {
  1: i32 count,
  2: list<RLEntry> items
}

struct SearchResult {
  1: InformationObject io,
  2: list<SearchResultEntry> entries
}

struct SearchResults {
  1: i32 count,
  2: list<SearchResult> items
}

struct GroupMembers {
  1: i32 count,
  2: list<UserRef> items
}

struct UserGroups {
  1: i32 count,
  2: list<Group> items
}

struct Range {
  // count from 0
  1: i32 start,
  2: i32 count
}

enum Scope {
  ALL = 1,
  MINE = 2,
  GROUP = 3,
  MATERIALIZED = 4 # useful during debug / inspection: shows only materialized items
}

enum InvalidOperationReason {
  DUPLICATE_ITEM = 1,
  UNHANDLED_EXCEPTION = 9
}

exception InvalidOperation {
  1: InvalidOperationReason what,
  2: string why,
  3: string details
}

service Scholarlynk {
  // return an authentication token
  /**
   * Authenticates a user. You can use either the 'uid' or the 'mail' to authenticate.
   *
   * returns an authentication token, for later use with 'login' (see login())
   */
  string authenticate(1: string username, 2: string password) throws (1: InvalidOperation e),
  
  bool login(1: string authToken) throws (1: InvalidOperation e),

  SearchResults search(1: string term, 2: Range range, 3: Scope scope) throws (1: InvalidOperation e),
  Item getItem(1: string id) throws (1: InvalidOperation e),

  /**
   * When we return items as part of a search result, we add a lot of informations
   * for example about the reading lists that contain the item etc.
   * Sometimes we need this information but all we have is the id of the 
   * the wanted information is not present in the plain getItem call.
   * 
   * This method is expected to be useful mostly in stateless web clients.
   * 
   */
  SearchResult getInformationObjectAsSearchResult(1: string id) throws (1: InvalidOperation e),

  /**
   * Search for users in a given scope.
   */
  UserResults userSearch(1: string term, 2: Range range, 3: Scope scope) throws (1: InvalidOperation e),

  UserGroups userGroups(1: string id, 2: Range range) throws (1: InvalidOperation e),

  /**
   * Search for groups in a given scope.
   */
  GroupResults groupSearch(1: string term, 2: Range range, 3: Scope scope) throws (1: InvalidOperation e),

  /**
   * Get the members of a group.
   */
  GroupMembers groupMembers(1: string id, 2: Range range) throws (1: InvalidOperation e),
  

  /**
   * Free keyword search for reading lists in a given scope.
   */
  ReadingListResults readingListSearch(1: string term, 2: Range range, 3: Scope scope) throws (1: InvalidOperation e),

  /**
   * Get a reading list by id.
   */
  ReadingList getReadingList(1: string id) throws (1: InvalidOperation e),

  /**
   * Get all entries for a given reading list.
   * 'filter' will restrict type type of the result entries. Defaults to "ALL".
   *
   * Normally getEntries will be invoked with READING_LISTS_ONLY on the MVL, for the root readinglist list.
   *
   */
  RLEntryResults getEntries(1: string id, 2: Range range, 3: RLEntryFilter filter, 4: string query) throws (1: InvalidOperation e),

  /**
   * Create a new item with the given id and metadata. It returns a http url where
   * the content has to be uploaded. It fails if the item already exists.
   */
  Url uploadItem(1: Item item) throws (1: InvalidOperation e),
  void commitUpload(1: string id) throws (1: InvalidOperation e),
  void abortUpload(1: string id) throws (1: InvalidOperation e),

  // original name
  void claim(1: string itemId, 2: string authorName) throws (1: InvalidOperation e),

  map<string, string> getUserProperties(1: string userId) throws (1: InvalidOperation e),
  void setUserProperties(1: string userId, 2: map<string, string> properties) throws (1: InvalidOperation e),
  User getUser(1: string userId) throws (1: InvalidOperation e),

  // content creation

  /**
   * Creates a new user and an empty MVL
   */
  string createUser(1: User user, 2: string password) throws (1: InvalidOperation e),

  // returns new group id
  string createGroup(1: Group user) throws (1: InvalidOperation e),
  void addUserToGroup(1: string groupId, 2: string userId) throws (1: InvalidOperation e),

  // returns new reading list id
  string createReadingList(1: ReadingList readingList) throws (1: InvalidOperation e),

  void deleteReadingList(1: string id) throws (1: InvalidOperation e),

  /**
   * Add an entry to a reading list poiting to an item.
   * (The user percieves this as adding an "item" to a reading list, but we keep the notion of entry)
   * returns the id of the newly created entry.
   */
  string addEntry(1: RLEntryDescription entry) throws (1: InvalidOperation e),

  /**
   * This method removes an entry. Use it to remove an information object from a reading list.
   * You normally have access to the entry id, because it's present in the getEntries invocation.
   */
  void removeEntry(1: string entryId) throws (1: InvalidOperation e),

  /**
   * Only changes those values which are modifiable.
   */
  void modifyEntry(1: RLEntryDescription entry) throws (1: InvalidOperation e),

  /**
   * Only changes those values which are modifiable and only if the object is yours.
   */
  void modifyInformationObject(1: InformationObject io) throws (1: InvalidOperation e),


  /**
   * We can tag any object. Usually we tag entries, at least this is what happens when the user tags a "document" inside a reading list.
   */
  void addTag(1: string objectId, 2: string tag) throws (1: InvalidOperation e),

  void removeTag(1: string objectId, 2: string tag) throws (1: InvalidOperation e),

  /**
   * add + removes tags. After the execution of this method the object will have exactly those tags.
   */
  void setTags(1: string objectId, 2: list<string> tags) throws (1: InvalidOperation e),


  // high level methods, probably can be done using the above primitives, but still useful, either to reduce traffic or to rely on serverside processing
  
  /**
   * set the rating for a given IO for the current logged in user. Equivalent of modifying the user's MVL entry for that information object.
   */
  
void rateInformationObject(1: string ioId, 2: double rating) throws (1: InvalidOperation e),
  

  // development only methods

  /**
   * Get currently logged in user.
   */
  User getCurrentUser() throws (1: InvalidOperation e),

  void modifyUser(1: User user) throws (1: InvalidOperation e),

  void resetUserPassword(1: User user, 2: string password) throws (1: InvalidOperation e),

  void materializeItem(1: string id) throws (1: InvalidOperation e),

  void deleteItem(1: string id) throws (1: InvalidOperation e),

  void test() throws (1: InvalidOperation e)
}