001/*
002 * Sonar, open source software quality management tool.
003 * Copyright (C) 2008-2012 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * Sonar 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 * Sonar 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
017 * License along with Sonar; if not, write to the Free Software
018 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
019 */
020package org.sonar.api.utils;
021
022import org.sonar.api.BatchComponent;
023import org.sonar.api.ServerComponent;
024
025import java.util.Date;
026
027/**
028 * A semaphore shared among all the processes that can connect to the central database.
029 * It's ignored when enabling the dry run mode.
030 *
031 * @since 3.4
032 */
033public interface Semaphores extends BatchComponent, ServerComponent {
034
035  /**
036   * Try to acquire a semaphore for a given duration.
037   * The semaphore is acquired if it's unlocked or if the max locking duration is reached.
038   * When the lock is acquired there will be a periodic ping of the
039   * server to update the semaphore and avoid it to be considered as
040   * outdated.
041   *
042   * @param name                 the key of the semaphore
043   * @param maxAgeInSeconds the max duration in seconds the semaphore will be considered unlocked if
044   *                        it was not updated. The value zero forces the semaphore to be acquired, whatever its status.
045   * @param updatePeriodInSeconds the period in seconds the semaphore will be updated.
046   * @return the semaphore, whatever its status (locked or unlocked). Can't be null.
047   */
048  Semaphore acquire(String name, int maxAgeInSeconds, int updatePeriodInSeconds);
049
050  /**
051   * Try to acquire a semaphore.
052   * The semaphore will be acquired only if there's no existing lock.
053   *
054   * @param name the key of the semaphore
055   * @return the semaphore, whatever its status (locked or unlocked). Can't be null.
056   */
057  Semaphore acquire(String name);
058
059  /**
060   * Release the lock on a semaphore by its name. Does nothing if the lock is already released.
061   *
062   * @param name the key of the semaphore
063   */
064  void release(String name);
065
066  class Semaphore {
067
068    private String name;
069    private boolean locked;
070    private Date locketAt;
071    private Date createdAt;
072    private Date updatedAt;
073    private Long durationSinceLocked;
074
075    public String getName() {
076      return name;
077    }
078
079    public Semaphore setName(String name) {
080      this.name = name;
081      return this;
082    }
083
084    public boolean isLocked() {
085      return locked;
086    }
087
088    public Semaphore setLocked(boolean locked) {
089      this.locked = locked;
090      return this;
091    }
092
093    public Date getLocketAt() {
094      return locketAt;
095    }
096
097    public Semaphore setLocketAt(Date locketAt) {
098      this.locketAt = locketAt;
099      return this;
100    }
101
102    public Date getCreatedAt() {
103      return createdAt;
104    }
105
106    public Semaphore setCreatedAt(Date createdAt) {
107      this.createdAt = createdAt;
108      return this;
109    }
110
111    public Date getUpdatedAt() {
112      return updatedAt;
113    }
114
115    public Semaphore setUpdatedAt(Date updatedAt) {
116      this.updatedAt = updatedAt;
117      return this;
118    }
119
120    public Long getDurationSinceLocked() {
121      return durationSinceLocked;
122    }
123
124    public Semaphore setDurationSinceLocked(Long durationSinceLocked) {
125      this.durationSinceLocked = durationSinceLocked;
126      return this;
127    }
128  }
129
130}