Rit::Base::Arc
Represents arcs.
Inherits from Rit::Base::Resource.
These can be called with the class name or any pred object.
Rit::Base::Arc->create( \%props, \%args )
Creates a new arc and stores in in the DB.
The props:
id : If undefined, gets a new id from the C<node_deq>
subj : Anything that L<Rit::Base::Resource/get> takes
pred : Anything that L<Rit::Base::Resource/get> takes, called as
L<Rit::Base::Pred>
implicit : Makes the arc both C<implicit> and C<indirect>
value : May be L<Rit::Base::Undef>, any L<Rit::Base::Literal> or a
L<Rit::Base::Resource>
obj : MUST be the id of the object, if given. Instead of C<value>
value_node : A L<Rit::Base::Resource>
created : Creation time. Defaults to now.
created_by : Creator. Defaults to request user or root
updated : Defaults to creation time or now.
active : Defaults to activate_new_arcs
submitted : Defaults to submit_new_arcs
common : Defaults to next new node id
replaces : Defaults to undef
source : Defaults to L</default_source>
read_access : Defaults to L</default_read_access>
write_access : Defaults to L</default_write_access>
valtype : Defaults to L<Rit::Base::Literal/this_valtype>
or L<Rit::Base::Pred/valtype>
arc_weight : Defaults to C<undef>
-1 for placing the arc last, upon activation,
changing the other properties as needed
Special args:
activate_new_arcs: Sets prop active submit_new_arcs: Sets prop submitted mark_updated updated
If value is a plain string, it's converted to an object based on Rit::Base::Pred/coltype.
subj, pred and value must be given.
A check is made for not creating an arc that already exists.
We do not allow arcs where subj and obj is the same resouce. (This check may catch bad cyclic recursive arc inferences.)
Inferences from the new arc weill be done directly or after /unlock.
Returns: The arc object
$a->subj
Returns: The subject Rit::Base::Resource of the arc
$a->pred
Returns: The Rit::Base::Pred of the arc
$a->value
Returns: The Rit::Base::Node value as a Rit::Base::Resource, Rit::Base::Literal or Rit::Base::Undef object. NB! Used internally.
The property value has special handling in its dynamic use for
resourcess. This means that you can only use this method as an ordinary
method call. Not dynamicly from TT.
Rather use /desig, /loc or /plain.
$a->value_node
Returns the common literal resource representing the literal. Assumes to only be called for literal arcs. Will always return the obj field.
$a->set_value_node() $a->set_value_node( $node )
Caller should do the authorization checks
$a->obj
Returns: The object Rit::Base::Resource of the arc.
If the arc points to a literal resource (value node), we will return the value node. Thus. You can't use this to determine if the arc ponts to a literal or not. Returns Rit::Base::Undef if nothing else.
For determining if the arc points at an obj, use /objtype.
$a->obj_id
Shortcut for $a->obj->id. Returns plain undef if no id.
$a->value_as_html
A designation of the value, in HTML.
This will use Rit::Base::Resource/as_html or any other
implementation of as_html for the value.
For removals, The deleted value will be displayd with a
line-through.
We method is placed in Arc rather than in Literal or other place since we display the html in the context of the arc status.
$a->value_diff_as_html
A designation of the value, in HTML.
This will use Rit::Base::Resource/as_html or any other
implementation of as_html for the value.
For removals, The deleted value will be displayd with a
line-through.
We method is placed in Arc rather than in Literal or other place since we display the html in the context of the arc status.
$a->value_desig
A designation of the value, suitable for admin interface
$a->value_sysdesig
Returns: A plain string with a designation of the value, suitable for admin interface
$a->created
Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.
$a->created_iso8601
PostgreSQL seems to always return times in the current local timezone, regardless of timezone used to store the date. This makes it useful for sorting and comparison. It also uses space to separate date and time.
Returns: The time as a string in ISO 8601 format, or undef
$a->updated
Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.
$a->updated_iso8601
PostgreSQL seems to always return times in the current local timezone, regardless of timezone used to store the date. This makes it useful for sorting and comparison. It also uses space to separate date and time.
Returns: The time as a string in ISO 8601 format, or undef
$a->mark_updated $a->mark_updated( $time )
Sets the update time to given time or now.
Returns the new time as a Rit::Base::Literal::Time
$a->activated
Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.
$a->deactivated
Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.
$a->deactivated_by
Returns: The Rit::Base::Resource of the deactivator, or Rit::Base::Undef.
$a->unsubmitted
NB: This is not the reverse of /submitted
unsubmitted means that the submission has been taken back. The
date of the submission is the /updated time, if the /submitted
flag is set.
Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.
$a->updated_by
See /created_by
$a->activated_by
Returns: The Rit::Base::Resource of the activator, or Rit::Base::Undef.
$a->created_by
Returns: The Rit::Base::Resource of the creator, or Rit::Base::Undef.
$a->version_id
$a->replaces_id
$a->replaces
$a->source
$a->read_access
$a->write_access
$a->is_owned_by( $agent )
$agent must be a Resource. It may be a Rit::Base::User.
Returns: true if $agent is regarded as an owner of the arc
TODO: Handle arcs where subj and obj has diffrent owners
TODO: Handle user that's members of a owner group
See: Rit::Base::Resource::is_owned_by
$a->view_flags A = active N = New S = Submitted O = Old Di = direct In = indirect Ex = explicit Im = implicit
Returns: A plain string the the direct/explicit status.
Example: In Im
$a->implicit
Returns: true if this arc is implicit
An implicit arc is always infered. It's always /indirect.
This is the oposite of /explicit.
$a->explicit
Returns: true if this arc is explicit
An explicit arc is an exisitng arc that's not only created by inference. It may be infered, but would exist even if it wasn't infered.
This is the oposite of /implicit.
$a->indirect
Returns: true if this arc is indirect
An indirect arc is (or can be) infered from other arcs. It may be /explicit or /implicit.
This is the oposite of /direct.
$a->direct
Returns: true if this arc is direct
A direct arc has (or can) not be infered from other arcs. It's always /explicit.
This is the oposite of /indirect.
$a->weight
Returns: the arc weight
May be undef
$a->arc_weight
The same as /weight
$a->distance
Returns: The number of arcs that inferes this arc
$a->active
Returns: true if this arc is active
$a->inactive
Returns: true if this arc is inactive
$a->submitted
NB: This is not the reverse of /unsubmitted
unsubmitted means that the submission has been taken back. The
date of the submission is the /updated time, if the /submitted
flag is set.
Returns: true if this arc is submitted
$a->is_new
This is a nonactvie and nonsubmitted arc that hasn't been deactivated.
Returns: true if this arc is new
$a->old
This is a arc that has been deactivated.
Returns: true if this arc is old
$a->active_version
May return undef;
Returns: The active arc, if there is one, even if it's this arc
$a->previous_active_version
May return undef;
Returns: The arc that was active and deactivated most recently, that is a version of this arc. Even if it's this same arc.
$a->version_by_date
May return undef;
See also Rit::Base::Arc::List/arc_active_on_date
Returns: The arc that was active at the given time.
$a->versions( $proplim, $args )
Returns: A Rit::Base::list of all versions of this arc
TODO: Make this a non-materialized list
$a->replaced_by
May return empty listref
Returns: A list of arcs replacing this version. Active or inactive
$a->common
TODO: Should be it's own class
Returns: The node representing the arc, regardless of version
$a->common_id
TODO: Should be it's own class
Returns: The node id representing the arc, regardless of version
$a->desig
Returns: a plain string representation of the arc
$a->sysdesig
Returns: a plain string representation of the arc, including the arc /id
$a->sysdesig_nosubj
Returns: a string representation of the arc, including the arc /id, not using name lookup for the subject.
(Mosly used in debugging in places there a subject lookup would cause infinite recursion.)
$a->table_row
$a->syskey
Returns: a unique predictable id representing this object
$a->is_removed
See if this arc is removed from the database. Only for arcs just removed but not yet removed from all caches.
Returns: 1 or 0
$a->is_removal
Is this an arc version representing the deletion of an arc?
Returns: 1 or 0
$a->is_arc
Returns: 1
$a->objtype
Returns: true if the /coltype of the /value is obj.
$a->coltype
Returns: the coltype the value will have. node.
$a->valtype
Valtype 0: Removal arcs
The valtypes are nodes. Coltypes are not, and there id's doesn't match the valtype ids.
??? Valtypes must uniquely identify the perl module class of the value.
TODO: Handle removal arcs transparently
Returns: the valtype node for this arc.
$a->this_valtype
This would be the same as the is property of this resource. But it
must only have ONE value. It's important for literal values.
This method will return the literal valtype for value resoruces.
See also: Rit::Base::Literal/this_valtype, /is_value_node.
Returns: The arc class resource.
$a->explain( \%args )
Explains how this arc has been infered.
Returns: reference to a list of hashes with the keys 'a', 'b' and 'c' pointing to the two arcs used in the inference and this resulting arc. The key 'rule' points to the rule used for the inference.
The list will be empty if this is'nt an infered arc.
... May remove arcs makred as /indirect if they arn't /explict.
The explain hash is set up by Rit::Base::Rule/validate_infere.
$a->deactivate( $arc, $args )
Must give the new active arc as arg. This will be called by /activate or by /remove.
Only active or submitted arcs can be deactivated.
Submitted arcs are not active but will be handled here. It will be deactivated as is if it was active, since its been replaced by a new arc.
The given new active arc would have triggered a /notify_change, rather than this method.
Returns: nothing
$a->vacuum( \%args )
Create or remove implicit arcs. Update implicit status.
For ACTIVE arcs pointing at literals it will also vacuum the literal before validating the value.
Returns: ---
$a->check_valtype( \%args )
Compares the arc valtype with the pred valtype
$a->check_value( \%args )
$a->reset_clean
Sets Rit::Base::Literal::String/clean based on /value, if it's a string. Updates the DB.
Returns: ---
$a->remove_duplicates( \%args )
Removes any other arcs identical to this.
Returns: ---
$a->has_value( $val, \%args )
$a->has_value({ $pred => $value }, \%args )
If given anything other than a hashref, calls Rit::Base::Object/matches and returns the result.
In the special case of negated pred matches: $a->has_value({ ${pred}_ne => [ $val1, $val2, ... ]}, \%args)
Instead of the normal OR logic: if( ($prop ne $val1) or ($prop ne $val2) ...
We will use AND: if( ($prop ne $val1) and ($prop ne $val2) ...
$a->value_equals( $val, \%args )
Supported args are
match clean arclim
Default $match is eq. Other supported values are ne, gt, lt, begins and like.
Default $clean is false. If $clean is true, strings will be
compared in clean mode. (You don't have to clean the $value by
yourself.)
Default arclim is active.
Returns: true if the arc /value $match $val, given clean
and arclim
$a->meets_arclim( $arclim )
$a->value_meets_proplim( $proplim ) $a->value_meets_proplim( $object )
Always true if proplim is undef or an empty hashref
If proplim is an object rather than an proplim, we check that the value is equal to the object.
Returns: boolean
$a->remove( \%args )
Removes the arc. Will also remove arcs pointing to/from the arc itself.
An arc is removed by the activation (and deactivation) of a new version with the value set to null and with valtype 0. That arc will have the activation and deactivation date identical. This will keep history about who requested the removal and who authorized it.
New (non-active) arcs can be removed directly by the authorized agent, without the creation of a removal arc.
A forced removal will not trigger Rit::Base::Resource/update_unseen_by.
Supported args are:
force force_recursive implicit res recursive
Default implicit bool is false.
A true value means that we want to remove an /implict arc.
A false value means that we want to remove an /explicit arc.
The implicit is used internally to ONLY remove arcs that's no
longer infered.
If called with a false value, it will remove the arc only if the arc can't be infered. If the arc can be infered, the arc will be changed from /explicit to /implicit.
Returns: the number of arcs removed.
$a->remove_recursive( \%args )
Called by /remove if given argument recursive
returns: -
$a->create_removal( \%args )
Returns: The removal arc
$a->update( \%props, \%args )
Proprties:
value: Calls L</set_value>
No other uses are implemented.
Example:
$a->update({ value => 'Hello world' });
Returns: The arc
$a->set_value( $new_value, \%args )
Sets the /value of the arc.
Determines if we are dealning with Rit::Base::Resource or Rit::Base::Literal.
Supported args are:
force_set_value force_set_value_same_version valtype value_node
If a new arc version is created, that creation may trigger a /notify_change. A foreced update will not trigger a /notify_change.
Returns: the arc changed, or the same arc
$a->set_pred( $pred, \%args )
Sets the pred to what we get from Rit::Base::Resource/get called from Rit::Base::Pred.
The old are will be removed with a removal and a new arc will be created, not as a new version. A new version of an arc can only have a diffrent value, not a diffrent subj or pred.
Returns: the arc changed, or the same arc
$a->submit( \%args )
Submits the arc
Returns: the number of changes
Exceptions: validation
$a->resubmit( \%args )
Submits the arc
Returns: the new arc
Exceptions: validation
$a->unsubmit
Unsubmits the arc
Returns: the number of changes
Exceptions: validation
$a->activate( \%args )
Activates the arc.
Supported args:
updated - time of activation force recursive - activate obj submitted arcs created by the same user
Returns: the number of changes
Exceptions: validation
$a->reactivate( \%args )
Tries to undo changes to the arc.
$a->set_replaces( $arc2, \%args )
$a->set_explicit $a->set_explicit( $bool )
Default $bool is true.
Returns: True if set to explicit
See also /set_implicit and /explicit
$a->set_implicit $a->set_implicit( $bool )
Default $bool is true.
Returns: True if set to explicit
See also /set_explicit and /implicit
$a->set_direct $a->set_direct( $bool )
Default $bool is true.
Returns: True if set to direct
See also /set_indirect and /direct
$a->set_indirect $a->set_indirect( $bool )
Default $bool is true.
Returns: True if set to indirect
See also /set_direct and /indirect
$a->set_weight( $int, \%args )
It may be set to undef to unset any previous value
Setting a new weight will create a new version if the arc is active.
Setting the weight to -1 will give it a weight of 0 and resort other arcs of the subject with the same predicate, to put this arc last. This will only be done for active arcs. Non-active arcs will have a weight of -1 until they are activated.
Supported args are:
force_same_version
Returns: the arc with the new weight
$arc->weight_last( \%args )
Increases the weight of all other arcs from the same subject with the same predicate, by 1.
Use $arc->set_weight(-1) to trigger this resort, since this method does not touch this arc.
The method only works on active arcs.
$n->get_by_rec( $rec, @extra )
Returns: a node
Exceptions: see /init.
$arc->get_by_rec_and_register($rec)
The same as Rit::Base::Resource/get_by_rec except that it's makes sure to register the arc with the subj and value nodes. The /init method will call /register_with_nodes but it will not be called if the arc is in the cache.
Returns: the arc
Exceptions: See /init
$a->init() $a->init( $rec ) $a->init( $rec, \%args ) $a->init( undef, \%args )
The existing subj and obj can be given, if known, to speed up the initialization process.
Supported args are:
subj value reset
Returns: the arc
$a->register_with_nodes
Returns: the arc
$a->deregister_with_nodes
Must only be called then the arc no longer exists.
Returns: the arc
$a->disregard
Each time arcs are created or removed the inference rules are checked. The arc may be infered from other arcs or other arcs may be infered from this arc.
Arcs that are about to be removed (in the current "transaction") or
already have been removed but still are refered to in other places,
has a positive disregard value to indicate that it should not bu
used for inferences.
We also has to differ between disregarded arcs and actually removed arcs.
Returns: True if arc is to be disregarded
TODO: Rewrite /vacuum
$a->not_disregarded
Returns true if this arc should not be disregarded.
The disregard does only need to be checked in the middle of an arc removal.
$a->schedule_check_create( \%args )
Schedueled checks of newly added/modified arcs
Returns: ---
$a->schedule_check_remove( \%args )
Schedueled checks of newly removed arcs
Returns: ---
$a->lock
Returns: ---
$a->unlock
Returns: ---
$a->unlock_all
Returns: ---
$a->clear_queue
Returns: ---
$a->validate_check( \%args )
Check if we should infere
for validation and remove: marking the arcs as to be disregarded in those methods. Check for $arc->disregard before considering an arc
Returns: true if this arc can be infered from other arcs
$a->create_check( \%args )
Creates new arcs infered from this arc.
May also change subject class.
Returns: ---
$a->remove_check( \%args )
Removes implicit arcs infered from this arc
Should only be called JUST BEFORE the arc is removed.
May also change subject class.
Returns: ---
$a->notify_change( \%args )
Will mark dependant nodes as updated unless for
$a->validate_range( \%args )
a) $a->validate_valtype( \%args ) b) Rit::Base::Arc->validate_valtype( \%args )
The second form allows for validation of an arc before it's
creation. In that case, the args must contain subj, pred,
value and valtype. valtype will default to pred range if not
given.
Returns: true or exception
$a->edit_link_html( \%args )
Displays link for updating arc
$a->info_updated_html( \%args )
Displays who and when arc was updated
timediff( $label )
Returns: Number of miliseconds from last call, formatted with
$label
Rit::Base, Rit::Base::Resource, Rit::Base::Pred, Rit::Base::List, Rit::Base::Search