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   *
039   * @param name                 the key of the semaphore
040   * @param maxDurationInSeconds the max duration in seconds the semaphore will be acquired. The value zero forces the semaphore to be acquired, whatever its status.
041   * @return the semaphore, whatever its status (locked or unlocked). Can't be null.
042   */
043  Semaphore acquire(String name, int maxDurationInSeconds);
044
045  /**
046   * Try to acquire a semaphore.
047   * The lock will be acquired only if there's no existing lock.
048   *
049   * @param name the key of the semaphore
050   * @return a lock containing information if the lock could be acquired or not, the duration since locked, etc.
051   */
052  Semaphore acquire(String name);
053
054  /**
055   * Release the lock on a semaphore by its name. Does nothing if the lock is already released.
056   *
057   * @param name the key of the semaphore
058   */
059  void release(String name);
060
061  class Semaphore {
062
063    private String name;
064    private boolean locked;
065    private Date locketAt;
066    private Date createdAt;
067    private Date updatedAt;
068    private Long durationSinceLocked;
069
070    public String getName() {
071      return name;
072    }
073
074    public Semaphore setName(String name) {
075      this.name = name;
076      return this;
077    }
078
079    public boolean isLocked() {
080      return locked;
081    }
082
083    public Semaphore setLocked(boolean locked) {
084      this.locked = locked;
085      return this;
086    }
087
088    public Date getLocketAt() {
089      return locketAt;
090    }
091
092    public Semaphore setLocketAt(Date locketAt) {
093      this.locketAt = locketAt;
094      return this;
095    }
096
097    public Date getCreatedAt() {
098      return createdAt;
099    }
100
101    public Semaphore setCreatedAt(Date createdAt) {
102      this.createdAt = createdAt;
103      return this;
104    }
105
106    public Date getUpdatedAt() {
107      return updatedAt;
108    }
109
110    public Semaphore setUpdatedAt(Date updatedAt) {
111      this.updatedAt = updatedAt;
112      return this;
113    }
114
115    public Long getDurationSinceLocked() {
116      return durationSinceLocked;
117    }
118
119    public Semaphore setDurationSinceLocked(Long durationSinceLocked) {
120      this.durationSinceLocked = durationSinceLocked;
121      return this;
122    }
123  }
124
125}