001/*
002 * SonarQube, open source software quality management tool.
003 * Copyright (C) 2008-2014 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * SonarQube is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * SonarQube is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.utils;
021
022import org.sonar.api.ServerComponent;
023import org.sonar.api.task.TaskComponent;
024
025import javax.annotation.Nullable;
026import java.util.Date;
027
028/**
029 * A semaphore shared among all the processes that can connect to the central database.
030 * It's ignored when enabling the dry run mode.
031 *
032 * @since 3.4
033 */
034public interface Semaphores extends TaskComponent, ServerComponent {
035
036  /**
037   * Try to acquire a semaphore for a given duration.
038   * The semaphore is acquired if it's unlocked or if the max locking duration is reached.
039   * When the lock is acquired there will be a periodic ping of the
040   * server to update the semaphore and avoid it to be considered as
041   * outdated.
042   *
043   * @param name                  the key of the semaphore
044   * @param maxAgeInSeconds       the max duration in seconds the semaphore will be considered unlocked if
045   *                              it was not updated. The value zero forces the semaphore to be acquired, whatever its status.
046   * @param updatePeriodInSeconds the period in seconds the semaphore will be updated.
047   * @return the semaphore, whatever its status (locked or unlocked). Can't be null.
048   */
049  Semaphore acquire(String name, int maxAgeInSeconds, int updatePeriodInSeconds);
050
051  /**
052   * Try to acquire a semaphore.
053   * The semaphore will be acquired only if there's no existing lock.
054   *
055   * @param name the key of the semaphore
056   * @return the semaphore, whatever its status (locked or unlocked). Can't be null.
057   */
058  Semaphore acquire(String name);
059
060  /**
061   * Release the lock on a semaphore by its name. Does nothing if the lock is already released.
062   *
063   * @param name the key of the semaphore
064   */
065  void release(String name);
066
067  class Semaphore {
068
069    private String name;
070    private boolean locked;
071    private Date lockedAt;
072    private Date createdAt;
073    private Date updatedAt;
074    private Long durationSinceLocked;
075
076    public String getName() {
077      return name;
078    }
079
080    public Semaphore setName(String name) {
081      this.name = name;
082      return this;
083    }
084
085    public boolean isLocked() {
086      return locked;
087    }
088
089    public Semaphore setLocked(boolean locked) {
090      this.locked = locked;
091      return this;
092    }
093
094    public Date getLockedAt() {
095      return lockedAt;
096    }
097
098    public Semaphore setLockedAt(@Nullable Date lockedAt) {
099      this.lockedAt = lockedAt;
100      return this;
101    }
102
103    public Date getCreatedAt() {
104      return createdAt;
105    }
106
107    public Semaphore setCreatedAt(@Nullable Date createdAt) {
108      this.createdAt = createdAt;
109      return this;
110    }
111
112    public Date getUpdatedAt() {
113      return updatedAt;
114    }
115
116    public Semaphore setUpdatedAt(@Nullable Date updatedAt) {
117      this.updatedAt = updatedAt;
118      return this;
119    }
120
121    public Long getDurationSinceLocked() {
122      return durationSinceLocked;
123    }
124
125    public Semaphore setDurationSinceLocked(Long durationSinceLocked) {
126      this.durationSinceLocked = durationSinceLocked;
127      return this;
128    }
129  }
130
131}