MediaWiki master
MediaWiki\Block\DatabaseBlock Class Reference

A DatabaseBlock (unlike a SystemBlock) is stored in the database, may give rise to autoblocks and may be tracked with cookies. More...

Inherits MediaWiki\Block\AbstractBlock.

Collaboration diagram for MediaWiki\Block\DatabaseBlock:

Public Member Functions

 __construct (array $options=[])
 Create a new block with specified option parameters on a user, IP or IP range.
 
 appliesToNamespace ( $ns)
 Checks if a block applies to a particular namespace.
Since
1.33
Parameters
int$ns
Returns
bool

 
 appliesToPage ( $pageId)
 Checks if a block applies to a particular page.This check does not consider whether $this->isUsertalkEditAllowed returns false, as the identity of the user making the hypothetical edit isn't known here (particularly in the case of IP hard blocks, range blocks, and auto-blocks).
Since
1.33
Parameters
int$pageId
Returns
bool

 
 appliesToRight ( $right)
 Determine whether the block prevents a given right.A right may be allowed or disallowed by default, or determined from a property on the block object. For certain rights, the property may be overridden according to global configs.
Since
1.33
Parameters
string$right
Returns
bool|null The block applies to the right, or null if unsure (e.g. unrecognized right or unset property)

 
 appliesToTitle (Title $title)
 Checks if a block applies to a particular title.This check does not consider whether $this->isUsertalkEditAllowed returns false, as the identity of the user making the hypothetical edit isn't known here (particularly in the case of IP hard blocks, range blocks, and auto-blocks).
Parameters
Title$title
Returns
bool

 
 doAutoblock ( $autoblockIP)
 Autoblocks the given IP, referring to this block.
 
 equals (DatabaseBlock $block)
 Check if two blocks are effectively equal.
 
 getBlocker ()
 Get the user who implemented this block.
 
 getBy ( $wikiId=self::LOCAL)
 Get the user id of the blocking sysop.
Parameters
string | false$wikiId(since 1.38)
Returns
int (0 for foreign users)

 
 getByName ()
 Get the username of the blocking sysop.
Returns
string

 
 getId ( $wikiId=self::LOCAL)
 Get the block ID.
Parameters
string | false$wikiId(since 1.38)
Returns
?int

 
 getIdentifier ( $wikiId=self::LOCAL)
 Get the information that identifies this block, such that a user could look up everything that can be found about this block.Typically a scalar ID (integer or string), but can also return a list of IDs, or an associative array encoding a composite ID. Must be safe to serialize as JSON.
Parameters
string | false$wikiId(since 1.38)
Returns
mixed Identifying information

 
 getIpHex ()
 Get the IP address of the single-IP block or the start of the range in hexadecimal form, or null if the target is not an IP.
 
 getParentBlockId ()
 
 getRangeEnd ()
 Get the IP address at the end of the range in hex form, or null if the target is not a range.
 
 getRangeStart ()
 Get the IP address at the start of the range in hex form, or null if the target is not a range.
 
 getRawRestrictions ()
 Get restrictions without loading from database if not yet loaded.
 
 getRedactedName ()
 Get the block name, but with autoblocked IPs hidden as per standard privacy policy.
 
 getRestrictions ()
 Getting the restrictions will perform a database query if the restrictions are not already loaded.
 
 getType ()
 Get the type of target for this particular block.
Returns
int|null AbstractBlock::TYPE_ constant

 
 insert ()
 Insert a block into the block table.
 
 isAutoblocking ( $x=null)
 Does the block cause autoblocks to be created?
 
 isExpired ()
 Has the block expired?
 
 isHardblock ( $x=null)
 Get/set whether the block is a hard block (affects logged-in users on a given IP/range)
 
 setBlocker ( $user)
 Set the user who implemented (or will implement) this block.
 
 setId ( $blockId)
 Set the block ID.
 
 setRestrictions (array $restrictions)
 
 update ()
 Update a block in the DB with new parameters.
 
 updateTimestamp ()
 Update the timestamp on autoblocks.
 
- Public Member Functions inherited from MediaWiki\Block\AbstractBlock
 appliesToPasswordReset ()
 Check if the block prevents a user from resetting their password.
 
 appliesToUsertalk (?Title $usertalk=null)
 Determine whether the block allows the user to edit their own user talk page.
 
 getExpiry ()
 Get the block expiry time.
 
 getHideName ()
 Get whether the block hides the target's username.
 
 getReasonComment ()
 Get the reason for creating the block.
 
 getRedactedTarget ()
 Get the target, with the IP address hidden behind an AutoBlockTarget if the block is an autoblock.
 
 getTarget ()
 Get the target as an object.
 
 getTargetName ()
 
 getTargetUserIdentity ()
 
 getTimestamp ()
 Get the timestamp indicating when the block was created.
 
 getWikiId ()
 
 isBlocking ( $target)
 
 isCreateAccountBlocked ( $x=null)
 Get or set the flag indicating whether this block blocks the target from creating an account.
 
 isEmailBlocked ( $x=null)
 Get or set the flag indicating whether this block blocks the target from sending emails.
 
 isIndefinite ()
 Is the block indefinite (with no fixed expiry)?
Since
1.44
Returns
bool

 
 isSitewide ( $x=null)
 Indicates that the block is a sitewide block.
 
 isUsertalkEditAllowed ( $x=null)
 Get or set the flag indicating whether this block blocks the target from editing their own user talk page.
 
 setExpiry ( $expiry)
 Set the block expiry time.
 
 setHideName ( $hideName)
 Set whether the block hides the target's username.
 
 setReason ( $reason)
 Set the reason for creating the block.
 
 setTarget ( $target)
 Set the target for this block.
 
 setTimestamp ( $timestamp)
 Set the timestamp indicating when the block was created.
 
 toArray ()
 
- Public Member Functions inherited from MediaWiki\Block\Block
 appliesToUsertalk ()
 Returns whether the block prevents user talk page access.
 
 isCreateAccountBlocked ()
 Get the flag indicating whether this block blocks the target from creating an account.
 
 isEmailBlocked ()
 Get the flag indicating whether this block blocks the target from sending emails.
 
 isHardblock ()
 Get whether the block is a hard block (affects logged-in users on a given IP/range).
 
 isSitewide ()
 Get whether the block is a sitewide block.
 
- Public Member Functions inherited from MediaWiki\DAO\WikiAwareEntity
 assertWiki ( $wikiId)
 Throws if $wikiId is different from the return value of getWikiId().
 

Static Public Member Functions

static getAutoblockExpiry ( $timestamp)
 Get the expiry timestamp for an autoblock created at the given time.
 
static getBlocksForIPList (array $ipChain, $applySoftBlocks, $fromPrimary=false)
 Get all blocks that match any IP from an array of IP addresses.
 
static isExemptedFromAutoblocks ( $ip)
 Checks whether a given IP is on the autoblock exemption list.
 
static newFromID ( $id)
 Load a block from the block ID.
 
static newFromRow ( $row)
 Create a new DatabaseBlock object from a database row.
 
static newFromTarget ( $specificTarget, $vagueTarget=null, $fromPrimary=false)
 Given a target and the target's type, get an existing block object if possible.
 
static newListFromTarget ( $specificTarget, $vagueTarget=null, $fromPrimary=false)
 This is similar to DatabaseBlock::newFromTarget, but it returns all the relevant blocks.
 

Additional Inherited Members

- Public Attributes inherited from MediaWiki\Block\Block
const BLOCK_TYPES
 Map block types to strings, to allow convenient logging.
 
const TYPE_AUTO = 4
 
const TYPE_IP = 2
 
const TYPE_RANGE = 3
 
const TYPE_USER = 1
 
- Public Attributes inherited from MediaWiki\DAO\WikiAwareEntity
const LOCAL = false
 Wiki ID value to use with instances that are defined relative to the local wiki.
 
- Protected Attributes inherited from MediaWiki\Block\AbstractBlock
bool $allowUsertalk = false
 
bool $blockCreateAccount = false
 
bool $blockEmail = false
 
string $expiry = ''
 
bool $hideName = false
 
bool $isHardblock
 
bool $isSitewide = true
 
CommentStoreComment $reason
 
BlockTarget null $target
 
string $timestamp = ''
 
string false $wikiId
 

Detailed Description

A DatabaseBlock (unlike a SystemBlock) is stored in the database, may give rise to autoblocks and may be tracked with cookies.

Such blocks* are more customizable than system blocks: they may be hard blocks, and they may be sitewide or partial.

Since
1.34 Renamed from Block.

Definition at line 31 of file DatabaseBlock.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Block\DatabaseBlock::__construct ( array $options = [])

Create a new block with specified option parameters on a user, IP or IP range.

Parameters
array$optionsParameters of the block, with options supported by AbstractBlock::__construct, and also:
  • auto: (bool) Is this an automatic block?
  • expiry: (string) Database timestamp of expiration of the block or 'infinity'
  • decodedExpiry: (string) The decoded expiry in MW 14-char format or 'infinity'
  • anonOnly: (bool) Only disallow anonymous actions
  • createAccount: (bool) Disallow creation of new accounts
  • enableAutoblock: (bool) Enable automatic blocking
  • blockEmail: (bool) Disallow sending emails
  • allowUsertalk: (bool) Allow the target to edit its own talk page
  • sitewide: (bool) Disallow editing all pages and all contribution actions, except those specifically allowed by other block flags
  • by: (UserIdentity) UserIdentity object of the blocker.
  • restrictions: (Restriction[]) Array of partial block restrictions
Since
1.26 $options array

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 70 of file DatabaseBlock.php.

References DB_REPLICA, MediaWiki\Block\DatabaseBlock\isAutoblocking(), MediaWiki\Block\Block\isCreateAccountBlocked(), MediaWiki\Block\Block\isEmailBlocked(), MediaWiki\Block\Block\isSitewide(), MediaWiki\Block\AbstractBlock\isUsertalkEditAllowed(), MediaWiki\Block\DatabaseBlock\setBlocker(), MediaWiki\Block\AbstractBlock\setExpiry(), and MediaWiki\Block\DatabaseBlock\setRestrictions().

Member Function Documentation

◆ appliesToNamespace()

MediaWiki\Block\DatabaseBlock::appliesToNamespace ( $ns)

Checks if a block applies to a particular namespace.

Since
1.33
Parameters
int$ns
Returns
bool

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 553 of file DatabaseBlock.php.

◆ appliesToPage()

MediaWiki\Block\DatabaseBlock::appliesToPage ( $pageId)

Checks if a block applies to a particular page.This check does not consider whether $this->isUsertalkEditAllowed returns false, as the identity of the user making the hypothetical edit isn't known here (particularly in the case of IP hard blocks, range blocks, and auto-blocks).

Since
1.33
Parameters
int$pageId
Returns
bool

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 571 of file DatabaseBlock.php.

◆ appliesToRight()

MediaWiki\Block\DatabaseBlock::appliesToRight ( $right)

Determine whether the block prevents a given right.A right may be allowed or disallowed by default, or determined from a property on the block object. For certain rights, the property may be overridden according to global configs.

Since
1.33
Parameters
string$right
Returns
bool|null The block applies to the right, or null if unsure (e.g. unrecognized right or unset property)

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 589 of file DatabaseBlock.php.

◆ appliesToTitle()

MediaWiki\Block\DatabaseBlock::appliesToTitle ( Title $title)

Checks if a block applies to a particular title.This check does not consider whether $this->isUsertalkEditAllowed returns false, as the identity of the user making the hypothetical edit isn't known here (particularly in the case of IP hard blocks, range blocks, and auto-blocks).

Parameters
Title$title
Returns
bool

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 535 of file DatabaseBlock.php.

◆ doAutoblock()

MediaWiki\Block\DatabaseBlock::doAutoblock ( $autoblockIP)

Autoblocks the given IP, referring to this block.

Deprecated
since 1.42, use DatabaseBlockStore::doAutoblock instead
Parameters
string$autoblockIPThe IP to autoblock.
Returns
int|false ID if an autoblock was inserted, false if not.

Definition at line 228 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Block\AbstractBlock\getWikiId(), and wfDeprecated().

◆ equals()

◆ getAutoblockExpiry()

static MediaWiki\Block\DatabaseBlock::getAutoblockExpiry ( $timestamp)
static

Get the expiry timestamp for an autoblock created at the given time.

Deprecated
since 1.42 No replacement, no known callers.
Parameters
string | int$timestamp
Returns
string

Definition at line 391 of file DatabaseBlock.php.

References wfDeprecated().

◆ getBlocker()

MediaWiki\Block\DatabaseBlock::getBlocker ( )

Get the user who implemented this block.

Returns
UserIdentity|null user object or null. May be a foreign user.

Implements MediaWiki\Block\Block.

Definition at line 661 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlockStore\doAutoblock(), and MediaWiki\Block\DatabaseBlockStore\insertBlock().

◆ getBlocksForIPList()

static MediaWiki\Block\DatabaseBlock::getBlocksForIPList ( array $ipChain,
$applySoftBlocks,
$fromPrimary = false )
static

Get all blocks that match any IP from an array of IP addresses.

Deprecated
since 1.44
Parameters
array$ipChainList of IPs (strings), usually retrieved from the X-Forwarded-For header of the request
bool$applySoftBlocksInclude soft blocks (anonymous-only blocks). These should only block anonymous and temporary users.
bool$fromPrimaryWhether to query the primary or replica DB
Returns
self[]
Since
1.22

Definition at line 467 of file DatabaseBlock.php.

References wfDeprecated().

◆ getBy()

MediaWiki\Block\DatabaseBlock::getBy ( $wikiId = self::LOCAL)

Get the user id of the blocking sysop.

Parameters
string | false$wikiId(since 1.38)
Returns
int (0 for foreign users)

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 644 of file DatabaseBlock.php.

◆ getByName()

MediaWiki\Block\DatabaseBlock::getByName ( )

Get the username of the blocking sysop.

Returns
string

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 652 of file DatabaseBlock.php.

◆ getId()

MediaWiki\Block\DatabaseBlock::getId ( $wikiId = self::LOCAL)

◆ getIdentifier()

MediaWiki\Block\DatabaseBlock::getIdentifier ( $wikiId = self::LOCAL)

Get the information that identifies this block, such that a user could look up everything that can be found about this block.Typically a scalar ID (integer or string), but can also return a list of IDs, or an associative array encoding a composite ID. Must be safe to serialize as JSON.

Parameters
string | false$wikiId(since 1.38)
Returns
mixed Identifying information

Implements MediaWiki\Block\Block.

Definition at line 488 of file DatabaseBlock.php.

◆ getIpHex()

MediaWiki\Block\DatabaseBlock::getIpHex ( )

Get the IP address of the single-IP block or the start of the range in hexadecimal form, or null if the target is not an IP.

Since
1.44
Returns
string|null

Definition at line 289 of file DatabaseBlock.php.

◆ getParentBlockId()

MediaWiki\Block\DatabaseBlock::getParentBlockId ( )
Since
1.34
Returns
int|null If this is an autoblock, ID of the parent block; otherwise null

Definition at line 330 of file DatabaseBlock.php.

◆ getRangeEnd()

MediaWiki\Block\DatabaseBlock::getRangeEnd ( )

Get the IP address at the end of the range in hex form, or null if the target is not a range.

Returns
string|null

Definition at line 277 of file DatabaseBlock.php.

References MediaWiki\Block\RangeBlockTarget\getHexRangeEnd().

◆ getRangeStart()

MediaWiki\Block\DatabaseBlock::getRangeStart ( )

Get the IP address at the start of the range in hex form, or null if the target is not a range.

Returns
string|null

Definition at line 266 of file DatabaseBlock.php.

References MediaWiki\Block\RangeBlockTarget\getHexRangeStart().

◆ getRawRestrictions()

MediaWiki\Block\DatabaseBlock::getRawRestrictions ( )

Get restrictions without loading from database if not yet loaded.

Access: internal
Returns
?Restriction[]

Definition at line 518 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlockStore\updateBlock().

◆ getRedactedName()

MediaWiki\Block\DatabaseBlock::getRedactedName ( )

Get the block name, but with autoblocked IPs hidden as per standard privacy policy.

Returns
string Text is escaped

Definition at line 371 of file DatabaseBlock.php.

References wfMessage().

◆ getRestrictions()

MediaWiki\Block\DatabaseBlock::getRestrictions ( )

Getting the restrictions will perform a database query if the restrictions are not already loaded.

Since
1.33
Returns
Restriction[]

Definition at line 499 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlockStore\doAutoblock(), and MediaWiki\Block\DatabaseBlock\equals().

◆ getType()

MediaWiki\Block\DatabaseBlock::getType ( )

Get the type of target for this particular block.

Returns
int|null AbstractBlock::TYPE_ constant

Autoblocks have whichever type corresponds to their target, so to detect if a block is an autoblock, we have to check the auto property instead.

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 479 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\BlockUser\__construct(), and MediaWiki\Block\DatabaseBlockStore\updateTimestamp().

◆ insert()

MediaWiki\Block\DatabaseBlock::insert ( )

Insert a block into the block table.

Will fail if there is a conflicting block (same name and options) already in the database.

Deprecated
since 1.36 Use DatabaseBlockStore::insertBlock instead. Passing a custom db connection is no longer supported since 1.42.
Returns
bool|array False on failure, assoc array on success: ('id' => block ID, 'autoIds' => array of autoblock IDs)

Definition at line 181 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Block\AbstractBlock\getWikiId(), and wfDeprecated().

◆ isAutoblocking()

MediaWiki\Block\DatabaseBlock::isAutoblocking ( $x = null)

Does the block cause autoblocks to be created?

Parameters
null | bool$x
Returns
bool

Definition at line 357 of file DatabaseBlock.php.

References wfSetVar().

Referenced by MediaWiki\Block\DatabaseBlock\__construct(), MediaWiki\Block\DatabaseBlockStore\doAutoblock(), MediaWiki\Block\DatabaseBlock\equals(), and MediaWiki\Block\DatabaseBlockStore\updateBlock().

◆ isExemptedFromAutoblocks()

static MediaWiki\Block\DatabaseBlock::isExemptedFromAutoblocks ( $ip)
static

Checks whether a given IP is on the autoblock exemption list.

Since
1.36
Deprecated
since 1.44 use AutoblockExemptionList::isExempt
Parameters
string$ipThe IP to check
Returns
bool

Definition at line 214 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), and wfDeprecated().

◆ isExpired()

MediaWiki\Block\DatabaseBlock::isExpired ( )

Has the block expired?

Returns
bool

Definition at line 240 of file DatabaseBlock.php.

References MediaWiki\Block\AbstractBlock\$timestamp, MediaWiki\Block\AbstractBlock\getExpiry(), wfDebug(), and wfTimestampNow().

◆ isHardblock()

MediaWiki\Block\DatabaseBlock::isHardblock ( $x = null)

Get/set whether the block is a hard block (affects logged-in users on a given IP/range)

Parameters
bool | null$x
Returns
bool

Reimplemented from MediaWiki\Block\AbstractBlock.

Definition at line 342 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlock\equals().

◆ newFromID()

static MediaWiki\Block\DatabaseBlock::newFromID ( $id)
static

Load a block from the block ID.

Deprecated
since 1.42 use DatabaseBlockStore::newFromID()
Parameters
int$idID to search for
Returns
DatabaseBlock|null

Definition at line 122 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), and wfDeprecated().

◆ newFromRow()

static MediaWiki\Block\DatabaseBlock::newFromRow ( $row)
static

Create a new DatabaseBlock object from a database row.

Deprecated
since 1.44 use DatabaseBlockStore::newFromRow
Parameters
stdClass$rowRow from the ipblocks table
Returns
DatabaseBlock

Definition at line 164 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), and wfDeprecated().

◆ newFromTarget()

static MediaWiki\Block\DatabaseBlock::newFromTarget ( $specificTarget,
$vagueTarget = null,
$fromPrimary = false )
static

Given a target and the target's type, get an existing block object if possible.

Deprecated
since 1.44
Parameters
string | UserIdentity | int | null$specificTargetA block target, which may be one of several types:
  • A user to block, in which case $target will be a User
  • An IP to block, in which case $target will be a User generated by using User::newFromName( $ip, false ) to turn off name validation
  • An IP range, in which case $target will be a String "123.123.123.123/18" etc
  • The ID of an existing block, in the format "#12345" (since pure numbers are valid usernames

Calling this with a user, IP address or range will not select autoblocks, and will only select a block where the targets match exactly (so looking for blocks on 1.2.3.4 will not select 1.2.0.0/16 or even 1.2.3.4/32).

Parameters
string | UserIdentity | int | null$vagueTargetAs above, but we will search for any block which affects that target (so for an IP address, get ranges containing that IP; and also get any relevant autoblocks). Leave empty or blank to skip IP-based lookups.
bool$fromPrimaryWhether to use the DB_PRIMARY database
Returns
DatabaseBlock|null (null if no relevant block could be found). The target and type of the returned block will refer to the actual block which was found, which might not be the same as the target you gave if you used $vagueTarget!

Definition at line 423 of file DatabaseBlock.php.

References wfDeprecated().

◆ newListFromTarget()

static MediaWiki\Block\DatabaseBlock::newListFromTarget ( $specificTarget,
$vagueTarget = null,
$fromPrimary = false )
static

This is similar to DatabaseBlock::newFromTarget, but it returns all the relevant blocks.

Deprecated
since 1.44
Since
1.34
Parameters
string | UserIdentity | int | null$specificTarget
string | UserIdentity | int | null$vagueTarget
bool$fromPrimary
Returns
DatabaseBlock[] Any relevant blocks

Definition at line 444 of file DatabaseBlock.php.

References wfDeprecated().

◆ setBlocker()

MediaWiki\Block\DatabaseBlock::setBlocker ( $user)

Set the user who implemented (or will implement) this block.

Parameters
UserIdentity$user

Definition at line 670 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlock\__construct().

◆ setId()

MediaWiki\Block\DatabaseBlock::setId ( $blockId)

Set the block ID.

Access: internal
Only for use in DatabaseBlockStore; private until 1.36
Parameters
int$blockId
Returns
self

Definition at line 314 of file DatabaseBlock.php.

◆ setRestrictions()

MediaWiki\Block\DatabaseBlock::setRestrictions ( array $restrictions)
Since
1.33
Parameters
Restriction[]$restrictions
Returns
self

Definition at line 527 of file DatabaseBlock.php.

Referenced by MediaWiki\Block\DatabaseBlock\__construct().

◆ update()

MediaWiki\Block\DatabaseBlock::update ( )

Update a block in the DB with new parameters.

The ID field needs to be loaded first.

Deprecated
since 1.36 Use DatabaseBlockStore::updateBlock instead.
Returns
bool|array False on failure, array on success: ('id' => block ID, 'autoIds' => array of autoblock IDs)

Definition at line 197 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Block\AbstractBlock\getWikiId(), and wfDeprecated().

◆ updateTimestamp()

MediaWiki\Block\DatabaseBlock::updateTimestamp ( )

Update the timestamp on autoblocks.

Deprecated
since 1.42, use DatabaseBlockStore::updateTimestamp instead

Definition at line 252 of file DatabaseBlock.php.

References MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Block\AbstractBlock\getWikiId(), and wfDeprecated().


The documentation for this class was generated from the following file: