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 */
020 package org.sonar.api.utils;
021
022 import org.sonar.api.ServerComponent;
023 import org.sonar.api.task.TaskComponent;
024
025 import javax.annotation.Nullable;
026 import 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 */
034 public 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 }