NAME

Rit::Base::Arc

DESCRIPTION

Represents arcs.

Inherits from Rit::Base::Resource.

Constructors

These can be called with the class name or any pred object.

create

  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

Accessors

subj

  $a->subj

Returns: The subject Rit::Base::Resource of the arc

pred

  $a->pred

Returns: The Rit::Base::Pred of the arc

value

  $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.

value_node

  $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.

set_value_node

  $a->set_value_node()

  $a->set_value_node( $node )

Caller should do the authorization checks

obj

  $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.

obj_id

  $a->obj_id

Shortcut for $a->obj->id. Returns plain undef if no id.

value_as_html

  $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.

value_diff_as_html

  $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.

value_desig

  $a->value_desig

A designation of the value, suitable for admin interface

value_sysdesig

  $a->value_sysdesig

Returns: A plain string with a designation of the value, suitable for admin interface

created

  $a->created

Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.

created_iso8601

  $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

updated

  $a->updated

Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.

updated_iso8601

  $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

mark_updated

  $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

activated

  $a->activated

Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.

deactivated

  $a->deactivated

Returns: The time as an Rit::Base::Literal::Time object, or Rit::Base::Undef.

deactivated_by

  $a->deactivated_by

Returns: The Rit::Base::Resource of the deactivator, or Rit::Base::Undef.

unsubmitted

  $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.

updated_by

  $a->updated_by

See /created_by

activated_by

  $a->activated_by

Returns: The Rit::Base::Resource of the activator, or Rit::Base::Undef.

created_by

  $a->created_by

Returns: The Rit::Base::Resource of the creator, or Rit::Base::Undef.

version_id

  $a->version_id

replaces_id

  $a->replaces_id

replaces

  $a->replaces

source

  $a->source

read_access

  $a->read_access

write_access

  $a->write_access

is_owned_by

  $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

view_flags

  $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

implicit

  $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.

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.

indirect

  $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.

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.

weight

  $a->weight

Returns: the arc weight

May be undef

arc_weight

  $a->arc_weight

The same as /weight

distance

  $a->distance

Returns: The number of arcs that inferes this arc

active

  $a->active

Returns: true if this arc is active

inactive

  $a->inactive

Returns: true if this arc is inactive

submitted

  $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

is_new

  $a->is_new

This is a nonactvie and nonsubmitted arc that hasn't been deactivated.

Returns: true if this arc is new

old

  $a->old

This is a arc that has been deactivated.

Returns: true if this arc is old

active_version

  $a->active_version

May return undef;

Returns: The active arc, if there is one, even if it's this arc

previous_active_version

  $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.

version_by_date

  $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.

versions

  $a->versions( $proplim, $args )

Returns: A Rit::Base::list of all versions of this arc

TODO: Make this a non-materialized list

replaced_by

  $a->replaced_by

May return empty listref

Returns: A list of arcs replacing this version. Active or inactive

common

  $a->common

TODO: Should be it's own class

Returns: The node representing the arc, regardless of version

common_id

  $a->common_id

TODO: Should be it's own class

Returns: The node id representing the arc, regardless of version

desig

  $a->desig

Returns: a plain string representation of the arc

sysdesig

  $a->sysdesig

Returns: a plain string representation of the arc, including the arc /id

sysdesig_nosubj

  $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.)

table_row

  $a->table_row

syskey

  $a->syskey

Returns: a unique predictable id representing this object

is_removed

  $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

is_removal

  $a->is_removal

Is this an arc version representing the deletion of an arc?

Returns: 1 or 0

is_arc

  $a->is_arc

Returns: 1

objtype

  $a->objtype

Returns: true if the /coltype of the /value is obj.

coltype

  $a->coltype

Returns: the coltype the value will have. node.

valtype

  $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.

this_valtype

  $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.

explain

  $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.

Public methods

deactivate

  $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

vacuum

  $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: ---

check_valtype

  $a->check_valtype( \%args )

Compares the arc valtype with the pred valtype

check_value

  $a->check_value( \%args )

reset_clean

  $a->reset_clean

Sets Rit::Base::Literal::String/clean based on /value, if it's a string. Updates the DB.

Returns: ---

remove_duplicates

  $a->remove_duplicates( \%args )

Removes any other arcs identical to this.

Returns: ---

has_value

  $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) ...

value_equals

  $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

meets_arclim

  $a->meets_arclim( $arclim )

value_meets_proplim

  $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

remove

  $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.

remove_recursive

  $a->remove_recursive( \%args )

Called by /remove if given argument recursive

returns: -

create_removal

  $a->create_removal( \%args )

Returns: The removal arc

update

  $a->update( \%props, \%args )

Proprties:

  value: Calls L</set_value>

No other uses are implemented.

Example:

 $a->update({ value => 'Hello world' });

Returns: The arc

set_value

  $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

set_pred

  $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

submit

  $a->submit( \%args )

Submits the arc

Returns: the number of changes

Exceptions: validation

resubmit

  $a->resubmit( \%args )

Submits the arc

Returns: the new arc

Exceptions: validation

unsubmit

  $a->unsubmit

Unsubmits the arc

Returns: the number of changes

Exceptions: validation

activate

  $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

reactivate

  $a->reactivate( \%args )

Tries to undo changes to the arc.

set_replaces

  $a->set_replaces( $arc2, \%args )

Private methods

set_explicit

  $a->set_explicit

  $a->set_explicit( $bool )

Default $bool is true.

Returns: True if set to explicit

See also /set_implicit and /explicit

set_implicit

  $a->set_implicit

  $a->set_implicit( $bool )

Default $bool is true.

Returns: True if set to explicit

See also /set_explicit and /implicit

set_direct

  $a->set_direct

  $a->set_direct( $bool )

Default $bool is true.

Returns: True if set to direct

See also /set_indirect and /direct

set_indirect

  $a->set_indirect

  $a->set_indirect( $bool )

Default $bool is true.

Returns: True if set to indirect

See also /set_direct and /indirect

set_weight

  $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

weight_last

  $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.

get_by_rec

  $n->get_by_rec( $rec, @extra )

Returns: a node

Exceptions: see /init.

get_by_rec_and_register

  $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

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

register_with_nodes

  $a->register_with_nodes

Returns: the arc

deregister_with_nodes

  $a->deregister_with_nodes

Must only be called then the arc no longer exists.

Returns: the arc

disregard

  $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

not_disregarded

  $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.

schedule_check_create

  $a->schedule_check_create( \%args )

Schedueled checks of newly added/modified arcs

Returns: ---

schedule_check_remove

  $a->schedule_check_remove( \%args )

Schedueled checks of newly removed arcs

Returns: ---

rollback

lock

  $a->lock

Returns: ---

unlock

  $a->unlock

Returns: ---

unlock_all

  $a->unlock_all

Returns: ---

clear_queue

  $a->clear_queue

Returns: ---

validate_check

  $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

create_check

  $a->create_check( \%args )

Creates new arcs infered from this arc.

May also change subject class.

Returns: ---

remove_check

  $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: ---

notify_change

  $a->notify_change( \%args )

Will mark dependant nodes as updated unless for

validate_range

  $a->validate_range( \%args )

validate_valtype

  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

edit_link_html

  $a->edit_link_html( \%args )

Displays link for updating arc

info_updated_html

  $a->info_updated_html( \%args )

Displays who and when arc was updated

default_source

default_read_access

default_write_access

use_class

list_class

as_rdf

Functions

timediff

  timediff( $label )

Returns: Number of miliseconds from last call, formatted with $label

SEE ALSO

Rit::Base, Rit::Base::Resource, Rit::Base::Pred, Rit::Base::List, Rit::Base::Search