Package org.exoplatform.caldav.rest

Class CaldavServerRest

java.lang.Object
org.exoplatform.caldav.rest.CaldavServerRest
@RestController @RequestMapping("/servers") public class CaldavServerRest extends Object
REST access to the CalDAV server registry. Reads are open to every authenticated user — the rows are credential-free by construction, and the browser needs the names and URLs to offer the connectors. Writes are for platform administrators; the ACL decision itself lives in the service, this layer only maps its exceptions onto statuses (404 for a missing object, 403 for a refused access, 400 with the message code for an invalid input — note the legacy JAX-RS resource of this add-on answers 401 where the org contract says 403; this new controller follows the contract).

  • Constructor Summary

    Constructors
    Constructor
    Description
    CaldavServerRest()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    org.exoplatform.caldav.model.CaldavManagedMode
    clearManagedMode(jakarta.servlet.http.HttpServletRequest request)
    Switches managed mode off: users choose their own server again.
    Map<String,Boolean>
    connectionRequirements()
    Whether each declared provider asks its user for anything, keyed by provider name — what a browser needs to decide whether its connect button opens a form or connects outright.
    CaldavDisconnectionPreview
    countConnectedUsers(jakarta.servlet.http.HttpServletRequest request, long serverId)
    How many users are connected to a server: what moving it to another credentials provider would disconnect.
    org.exoplatform.caldav.model.CaldavServer
    createServer(jakarta.servlet.http.HttpServletRequest request, org.exoplatform.caldav.model.CaldavServer server)
    Declares a new CalDAV server.
    void
    deleteServer(jakarta.servlet.http.HttpServletRequest request, long serverId)
    Deletes a declared CalDAV server, refused with a 409 — carrying caldav.server.referenced:<count> — while connected accounts still reference it.
    List<org.exoplatform.caldav.model.ForeignWriter>
    getForeignWriters(jakarta.servlet.http.HttpServletRequest request, long serverId)
    Serves the other eXo deployments seen writing meeting copies into this server's accounts (EXO-89824) - what the drawer states under the behaviours the server itself has been seen having.
    org.exoplatform.caldav.model.CaldavManagedMode
    getManagedMode(jakarta.servlet.http.HttpServletRequest request)
    Whether this deployment chooses the CalDAV server on its users' behalf, which one, and which groups it does not reach.
    List<MirrorPassReport>
    getMirrorReports()
    What the last pass over each connected user's meeting copies found and moved.
    Map<String,String>
    getProviderConfig(jakarta.servlet.http.HttpServletRequest request, long serverId)
    Serves the provider configuration of a declared server - what the drawer repopulates its provider fields from.
    org.springframework.http.ResponseEntity<org.springframework.core.io.InputStreamResource>
    getServerImage(jakarta.servlet.http.HttpServletRequest request, long serverId)
    Serves the uploaded image of a declared CalDAV server — the icon the admin table and the connectors list render.
    List<org.exoplatform.caldav.model.CaldavServer>
    getServers(jakarta.servlet.http.HttpServletRequest request)
    Lists every declared CalDAV server, active or not — the admin section shows both, and nothing in a row is secret.
    org.exoplatform.caldav.model.CaldavSyncTuning
    getTuning()
    How often and how widely eXo synchronises CalDAV accounts.
    org.springframework.http.ResponseEntity<Map<String,Object>>
    onRefusal(org.springframework.web.server.ResponseStatusException refusal)
    Puts a refusal's message code in the body the browser reads.
    CaldavDisconnectionPreview
    previewManagedMode(jakarta.servlet.http.HttpServletRequest request, CaldavManagedModeRequest body)
    How many accounts a managed-mode change would disconnect, before it is applied: the users managed mode attached that the proposed state no longer governs.
    org.exoplatform.caldav.model.CaldavManagedMode
    saveManagedMode(jakarta.servlet.http.HttpServletRequest request, CaldavManagedModeRequest body)
    Records the server the instance synchronises everybody with, and the groups that choice does not reach.
    org.exoplatform.caldav.model.CaldavSyncTuning
    saveTuning(org.exoplatform.caldav.model.CaldavSyncTuning tuning)
    Records how often and how widely eXo synchronises.
    org.exoplatform.caldav.model.CaldavServer
    setServerActive(jakarta.servlet.http.HttpServletRequest request, long serverId, boolean active)
    Activates or deactivates a declared CalDAV server.
    org.exoplatform.caldav.model.CaldavServer
    updateServer(jakarta.servlet.http.HttpServletRequest request, long serverId, org.exoplatform.caldav.model.CaldavServer server)
    Updates a declared CalDAV server.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CaldavServerRest

      public CaldavServerRest()

  • Method Details

    • getTuning

      @GetMapping("/tuning") @Secured("users") public org.exoplatform.caldav.model.CaldavSyncTuning getTuning()
      How often and how widely eXo synchronises CalDAV accounts.

      Readable by any authenticated user because nothing here is secret and the administration screen renders before it knows who is looking; writing is another matter.

      Returns:
      the tuning in force

    • saveTuning

      @PutMapping("/tuning") @Secured("administrators") public org.exoplatform.caldav.model.CaldavSyncTuning saveTuning(@RequestBody org.exoplatform.caldav.model.CaldavSyncTuning tuning)
      Records how often and how widely eXo synchronises.

      Takes effect on the next synchronisation, not on the next restart: the engine reads these where it uses them rather than capturing them when its beans are built.

      Parameters:
      tuning - the values to store
      Returns:
      the tuning now in force

    • getManagedMode

      @GetMapping("/managed") @Secured("administrators") public org.exoplatform.caldav.model.CaldavManagedMode getManagedMode(jakarta.servlet.http.HttpServletRequest request)
      Whether this deployment chooses the CalDAV server on its users' behalf, which one, and which groups it does not reach.

      Administrators only: the exclusions and the server's name are the administration screen's facts. The per-viewer managedForMe is kept in the payload for the login-time attachment (EXO-89653); no user page reads this today.

      Parameters:
      request - the HTTP request, carrying the authenticated user
      Returns:
      the mode as it stands for the caller

    • saveManagedMode

      @PutMapping("/managed") @Secured("administrators") public org.exoplatform.caldav.model.CaldavManagedMode saveManagedMode(jakarta.servlet.http.HttpServletRequest request, @RequestBody CaldavManagedModeRequest body)
      Records the server the instance synchronises everybody with, and the groups that choice does not reach.

      Switching managed mode on attaches a whole population, so the row has to be one they could actually be attached to: an unknown or deactivated registration, or one whose provider asks the user for something, is refused with the message code the drawer renders.

      Parameters:
      request - the HTTP request, carrying the authenticated user
      body - the registration to manage with and the excluded groups
      Returns:
      the mode now in force, as it stands for the calling administrator

    • previewManagedMode

      @PostMapping("/managed/preview") @Secured("administrators") public CaldavDisconnectionPreview previewManagedMode(jakarta.servlet.http.HttpServletRequest request, @RequestBody(required=false) CaldavManagedModeRequest body)
      How many accounts a managed-mode change would disconnect, before it is applied: the users managed mode attached that the proposed state no longer governs. A body with no server previews switching managed mode off.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      body - the proposed server (null to preview switching off) and excluded groups
      Returns:
      the number of accounts the change would disconnect

    • countConnectedUsers

      @GetMapping("/{serverId}/connected-users/count") @Secured("administrators") public CaldavDisconnectionPreview countConnectedUsers(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId)
      How many users are connected to a server: what moving it to another credentials provider would disconnect.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - the server
      Returns:
      the number of users connected to it

    • clearManagedMode

      @DeleteMapping("/managed") @Secured("administrators") public org.exoplatform.caldav.model.CaldavManagedMode clearManagedMode(jakarta.servlet.http.HttpServletRequest request)
      Switches managed mode off: users choose their own server again.

      Nothing is severed by this and nothing was severed by switching it on — the mode governs which affordances are offered, never the connections that already exist.

      Parameters:
      request - the HTTP request, carrying the authenticated user
      Returns:
      the mode now in force, which names no server

    • getMirrorReports

      @GetMapping("/mirror/reports") @Secured("administrators") public List<MirrorPassReport> getMirrorReports()
      What the last pass over each connected user's meeting copies found and moved.

      Administrators only, and for a reason the reads above do not have: a row here names a user and says something about the state of their calendar. Nothing in it is a credential, but it is not the sort of thing every authenticated caller has any business enumerating.

      In memory and therefore empty after a restart, until each account synchronises again. That is stated in the screen rather than hidden here.

      Returns:
      the last pass of every user that has had one, newest first

    • connectionRequirements

      @GetMapping("/connection-requirements") @Secured("users") public Map<String,Boolean> connectionRequirements()
      Whether each declared provider asks its user for anything, keyed by provider name — what a browser needs to decide whether its connect button opens a form or connects outright.

      Open to every authenticated user, unlike the provider registry itself, which is administrators-only: this answers about the connectors offered to the caller, not about how the instance is configured.

      Returns:
      one entry per declared provider name, true when the user must supply something

    • getServers

      @GetMapping @Secured("users") public List<org.exoplatform.caldav.model.CaldavServer> getServers(jakarta.servlet.http.HttpServletRequest request)
      Lists every declared CalDAV server, active or not — the admin section shows both, and nothing in a row is secret.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      Returns:
      every registration

    • createServer

      @PostMapping @Secured("administrators") public org.exoplatform.caldav.model.CaldavServer createServer(jakarta.servlet.http.HttpServletRequest request, @RequestBody org.exoplatform.caldav.model.CaldavServer server)
      Declares a new CalDAV server.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      server - registration to create
      Returns:
      the created registration, carrying its id and provider name

    • updateServer

      @PutMapping("/{serverId}") @Secured("administrators") public org.exoplatform.caldav.model.CaldavServer updateServer(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId, @RequestBody org.exoplatform.caldav.model.CaldavServer server)
      Updates a declared CalDAV server.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration
      server - new values of the registration
      Returns:
      the updated registration

    • setServerActive

      @PatchMapping("/{serverId}/status") @Secured("administrators") public org.exoplatform.caldav.model.CaldavServer setServerActive(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId, @RequestParam("active") boolean active)
      Activates or deactivates a declared CalDAV server.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration
      active - whether users may connect to this server
      Returns:
      the updated registration

    • getProviderConfig

      @GetMapping("/{serverId}/provider-config") @Secured("administrators") public Map<String,String> getProviderConfig(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId)
      Serves the provider configuration of a declared server - what the drawer repopulates its provider fields from. Secret values are never in the answer.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration
      Returns:
      the stored values without any secret

    • getForeignWriters

      @GetMapping("/{serverId}/foreign-writers") @Secured("administrators") public List<org.exoplatform.caldav.model.ForeignWriter> getForeignWriters(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId)
      Serves the other eXo deployments seen writing meeting copies into this server's accounts (EXO-89824) - what the drawer states under the behaviours the server itself has been seen having.

      Its own request rather than a field on the registration, like the provider-config read above: the condition is evidence the inbound pass wrote, and nothing an administrator saves may carry it back.

      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration
      Returns:
      the deployments seen writing here, most recently seen first, empty when none has been

    • deleteServer

      @DeleteMapping("/{serverId}") @Secured("administrators") public void deleteServer(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId)
      Deletes a declared CalDAV server, refused with a 409 — carrying caldav.server.referenced:<count> — while connected accounts still reference it.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration

    • getServerImage

      @GetMapping("/{serverId}/image") @Secured("users") public org.springframework.http.ResponseEntity<org.springframework.core.io.InputStreamResource> getServerImage(jakarta.servlet.http.HttpServletRequest request, @PathVariable("serverId") long serverId)
      Serves the uploaded image of a declared CalDAV server — the icon the admin table and the connectors list render.
      Parameters:
      request - the HTTP request, carrying the authenticated user
      serverId - technical identifier of the registration
      Returns:
      the image bytes as PNG

    • onRefusal

      @ExceptionHandler(org.springframework.web.server.ResponseStatusException.class) public org.springframework.http.ResponseEntity<Map<String,Object>> onRefusal(org.springframework.web.server.ResponseStatusException refusal)
      Puts a refusal's message code in the body the browser reads.

      The controller methods refuse with ResponseStatusException(status, code), and Spring Boot's default error body does not carry the reason on this platform - the browser received {"status":400,"error":"Bad Request"} and nothing else, so the drawers fell back to "could not be saved" for every rule (EXO-89652). The same shape CaldavShareRest answers its own failures with: the status, and the code under message, which is what the JS services read.

      Parameters:
      refusal - the refusal a controller method threw
      Returns:
      the same status, with the code in the body