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
}

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
}

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
}

// deprecated
struct RLEntryReadingList {
  1: string id,
  2: string name,
  3: UserRef owner,
  4: list<string> tags // the tags of this documents in the context of this reading list.
  5: string entryId
}

/**
 * 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: Item item,
  4: ReadingList readingList, // either item or reading list
  3: list<string> tags,
  5: double rating
}

struct RLEntryDescription {
  1: string id, 
  2: string readingListId,
  3: string itemId, // should be renamed to "informationObjectId"
  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: Item item,
  3: ReadingList readingList, // either item or readingList
  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
}

exception InvalidOperation {
  1: i32 what,
  2: string why
}

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),
  
  bool login(1: string authToken),

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

  /**
   * 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),

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

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

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

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

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

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

  /**
   * 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),

  /**
   * 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),
  void abortUpload(1: string id),

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

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

  // content creation

  /**
   * Creates a new user and an empty MVL
   */
  string createUser(1: User user),

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

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

  /**
   * 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),

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

  /**
   * 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),
  void removeTag(1: string objectId, 2: string tag),

  // 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);
  

  // development only methods

  /**
   * Get currently logged in user.
   */
  User getCurrentUser(),


  void materializeItem(1: string id),

  void deleteItem(1: string id),

  void test()
}